CI: generate PDF documentation (#162)

Add steps in `make.bat`, `Makefile` and `tox.ini` for compiling the PDF documentation, and include them in CI/CD. Co-authored-by: Dominik Gresch <[email protected]>
ansys · Jan 30, 2023 · 917ae7b · 917ae7b
1 parent d6c4ca5
commit 917ae7b
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 7 deletions.
diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
@@ -167,7 +167,22 @@ jobs:
         uses: actions/upload-artifact@v2
         with:
           name: documentation-html
-          path: .tox/doc_out/
+          path: .tox/doc_out/html
+          retention-days: 7
+
+      - name: "Install OS packages for PDF"
+        run: |
+          sudo apt-get install latexmk texlive-latex-extra
+
+      - name: "Generate the PDF documentation with tox"
+        run: |
+          tox -e doc-linux-pdf
+
+      - name: "Upload PDF Documentation"
+        uses: actions/upload-artifact@v2
+        with:
+          name: documentation-pdf
+          path: .tox/doc_out/latex/ansys-dpf-composites.pdf
           retention-days: 7
 
   build-package:

diff --git a/doc/Makefile b/doc/Makefile
@@ -24,3 +24,9 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(SOURCEDIR)/examples
 	find . -type d -name "_autosummary" -exec rm -rf {} +
+
+# Customized pdf fov svg format images
+pdf:
+	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1
diff --git a/doc/make.bat b/doc/make.bat
@@ -12,6 +12,7 @@ set BUILDDIR=_build
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
+if "%1" == "pdf" goto pdf
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -37,6 +38,13 @@ goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:pdf
+%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+cd "%BUILDDIR%\latex"
+for %%f in (*.tex) do (
+pdflatex "%%f" --interaction=nonstopmode)
 
 :end
 popd
diff --git a/tox.ini b/tox.ini
@@ -70,9 +70,7 @@ basepython =
 allowlist_externals  =
     poetry
 commands =poetry install -E docs
-    poetry build
-    poetry run pip install --find-links=.\dist ansys-dpf-composites
-    poetry run sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out" --color -n -vW --keep-going -bhtml
+    poetry run sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out/html" --color -n -vW --keep-going -bhtml
 
 [testenv:doc-linux]
 description = Check if documentation generates properly
@@ -83,6 +81,17 @@ passenv =  PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT
 allowlist_externals  =
     poetry, xvfb-run
 commands =poetry install -E docs
-    poetry build
-    poetry run pip install --find-links=.\dist ansys-dpf-composites
-    xvfb-run poetry run sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out" --color -n -vW --keep-going -bhtml
+    xvfb-run poetry run sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out/html" --color -n -vW --keep-going -bhtml
+
+[testenv:doc-linux-pdf]
+description = Check if documentation generates properly
+setenv = REPO_ROOT = {toxinidir}
+basepython =
+ python3.9
+passenv =  PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT
+allowlist_externals  =
+    poetry, xvfb-run, bash, test
+commands =poetry install -E docs
+    -xvfb-run poetry run sphinx-build -M latex -d "{toxworkdir}/doc_doctree" doc/source "{toxworkdir}/doc_out/latex" --color --keep-going
+    -bash -c "cd {toxworkdir}/doc_out/latex/ && latexmk -f -r latexmkrc -pdf *.tex -interaction=nonstopmode"
+    test -f "{toxworkdir}/doc_out/latex/ansys-dpf-composites.pdf"