diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index c56313c51..b82db5e90 100644 --- a/.github/workflows/ci_cd.yml +++ b/.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 }} diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index d788dd443..abea292f0 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -104,7 +104,7 @@ 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 @@ -112,3 +112,10 @@ jobs: 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 \ No newline at end of file diff --git a/doc/make.bat b/doc/make.bat index c98a36031..d1a3777b4 100644 --- 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 ( diff --git a/doc/source/conf.py b/doc/source/conf.py index e7f0befe3..77704ab03 100644 --- a/doc/source/conf.py +++ b/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: """ diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 241502736..e45efbfb6 100644 --- a/doc/source/contribute.rst +++ b/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--``: 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 ------------ diff --git a/tox.ini b/tox.ini index c5daf3064..cae0bd133 100644 --- a/tox.ini +++ b/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 \ No newline at end of file + {html,pdf}-linux: make -C doc {env:BUILDER} + {html,pdf}-windows: .\doc\make.bat {env:BUILDER} \ No newline at end of file