fix: enable pdf documentation generation

.github/workflows/ci_cd.yml

@@ -88,7 +88,7 @@ jobs:
           sudo apt install latexmk texlive-latex-extra
 
       - name: Generate the documentation with tox
-        run: tox -e doc
+        run: tox -e doc-html-${{ runner.os == 'Linux' && 'linux' || 'windows' }},doc-pdf-${{ runner.os == 'Linux' && 'linux' || 'windows' }}
 
       - name: Upload HTML Documentation
         uses: actions/upload-artifact@v4
@@ -97,6 +97,13 @@ jobs:
           path: doc/_build/html
           retention-days: 7
 
+      - name: Upload PDF Documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-pdf
+          path: doc/_build/latex/*.pdf
+          retention-days: 7
+
   smoke-tests:
     name: Build and Smoke tests
     runs-on: ${{ matrix.os }}

.github/workflows/nightly.yml

@@ -104,11 +104,18 @@ jobs:
           sudo apt install texlive-latex-extra
 
       - name: Generate the documentation with tox
-        run: tox -e doc
+        run: tox -e doc-html-${{ runner.os == 'Linux' && 'linux' || 'windows' }},doc-pdf-${{ runner.os == 'Linux' && 'linux' || 'windows' }}
 
       - name: Upload HTML Documentation
         uses: actions/upload-artifact@v4
         with:
           name: documentation-html
           path: doc/_build/html
           retention-days: 7
+
+      - name: Upload PDF Documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-pdf
+          path: doc/_build/latex/*.pdf
+          retention-days: 7

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 (

doc/source/conf.py

@@ -382,6 +382,12 @@ def prepare_jinja_env(jinja_env) -> None:
     ),
 }
 
+# Configuration for Sphinx Design
+# -----------------------------------------------------------------------------
+suppress_warnings = [
+    "design.fa-build",
+]
+
 
 def archive_examples(app: sphinx.application.Sphinx) -> None:
     """

doc/source/contribute.rst

@@ -77,7 +77,7 @@ The following environment commands are provided:
 - ``tox -e style``: Checks for coding style quality.
 - ``tox -e py``: Checks for unit tests.
 - ``tox -e py-coverage``: Checks for unit testing and code coverage.
-- ``tox -e doc``: Checks for documentation building.
+- ``tox -e doc-<html/pdf>-<linux/windows>``: Checks for documentation building. For example, to generate html documentation on linux, run ``tox -e doc-html-linux``
 
 Raw testing
 ^^^^^^^^^^^
@@ -120,15 +120,14 @@ For building documentation, you can manually run these commands:
 
 .. code:: bash
 
-    python archive_examples.py
-    make -C doc html
+    make -C doc html # for building documentation on Linux
 
 However, the recommended way of checking documentation integrity is to use
-``tox``:
+``tox``. For example, the following can be run on Linux:
 
 .. code:: bash
 
-    tox -e doc && your_browser_name .tox/doc_out/index.html
+    tox -e doc-html-linux && your_browser_name doc/_build/html/index.html
 
 Distributing
 ------------

tox.ini

@@ -1,7 +1,7 @@
 [tox]
 description = Default tox environments list
 envlist =
-    style,py{310,311,312,313}{,-coverage},doc
+    style,py{310,311,312,313}{,-coverage}
 skip_missing_interpreters = true
 
 [testenv]
@@ -38,10 +38,24 @@ commands =
     pre-commit install
     pre-commit run --all-files --show-diff-on-failure
 
-[testenv:doc]
-description = Check if documentation generates properly
+[testenv:doc-{html,pdf}-{linux,windows}]
+description =
+    Environment for
+    html: html documentation generation
+    pdf: pdf documentation generation
+    linux: on linux
+    windows: on windows
+platform = linux: linux
+           windows: win32
+setenv =
+    SOURCE_DIR = doc/source
+    BUILD_DIR = doc/_build
+    html: BUILDER = html
+    pdf: BUILDER = pdf
+    html,pdf: BUILDER_OPTS = --color -v -j auto --keep-going
 deps =
     -e .[doc]
 allowlist_externals = make
 commands =
-    sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto
+    {html,pdf}-linux: make -C doc {env:BUILDER}
+    {html,pdf}-windows: .\doc\make.bat {env:BUILDER}