From aa2199894cac1f47e3705efd22480d51e7b48d7c Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 12:26:15 +0100 Subject: [PATCH 01/11] fix: enable pdf documentation generation --- .github/workflows/ci_cd.yml | 9 ++++++++- .github/workflows/nightly.yml | 9 ++++++++- tox.ini | 16 +++++++++++++--- 3 files changed, 29 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index c56313c51..56af44eab 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,doc-pdf - 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..fe80db970 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,doc-pdf - 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/tox.ini b/tox.ini index c5daf3064..af84ca295 100644 --- a/tox.ini +++ b/tox.ini @@ -38,10 +38,20 @@ 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}] +description = + Environment for + html: html documentation generation + pdf: pdf documentation generation +setenv = + SOURCE_DIR = doc/source + BUILD_DIR = doc/_build + html: BUILDER = html + pdf: BUILDER = latex + html,pdf: BUILDER_OPTS = --color -v -j auto -W --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: sphinx-build -M "{env:BUILDER}" "{env:SOURCE_DIR}" "{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} + pdf: pdflatex -interaction=nonstopmode -output-directory="{env:BUILD_DIR}/{env:BUILDER}" {env:BUILD_DIR}/{env:BUILDER}/*.tex \ No newline at end of file From d31e53704435c4cc2c137e196ea01290d883a933 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 12:37:57 +0100 Subject: [PATCH 02/11] fix: fontawesome errors --- doc/source/conf.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index e7f0befe3..c118e6d4c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -382,6 +382,14 @@ def prepare_jinja_env(jinja_env) -> None: ), } +# Configuration for Sphinx Design +# ----------------------------------------------------------------------------- +sd_fontawesome_latex = True + +suppress_warnings = [ + "design.fa-build", +] + def archive_examples(app: sphinx.application.Sphinx) -> None: """ From c27eca8bc255192230ecc60ae90321590cee42c3 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 12:44:32 +0100 Subject: [PATCH 03/11] fix: don't treat warnings as errors --- doc/source/conf.py | 1 - tox.ini | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index c118e6d4c..da44384c3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -390,7 +390,6 @@ def prepare_jinja_env(jinja_env) -> None: "design.fa-build", ] - def archive_examples(app: sphinx.application.Sphinx) -> None: """ Create a zip archive for each listed example included in the examples folder. diff --git a/tox.ini b/tox.ini index af84ca295..e1baec64d 100644 --- a/tox.ini +++ b/tox.ini @@ -48,7 +48,7 @@ setenv = BUILD_DIR = doc/_build html: BUILDER = html pdf: BUILDER = latex - html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going + html,pdf: BUILDER_OPTS = --color -v -j auto --keep-going deps = -e .[doc] allowlist_externals = make From 10c7dd8fd4e7038d866c3a9447fa0040ccd2f52f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 25 Mar 2025 11:44:49 +0000 Subject: [PATCH 04/11] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/source/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/conf.py b/doc/source/conf.py index da44384c3..c118e6d4c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -390,6 +390,7 @@ def prepare_jinja_env(jinja_env) -> None: "design.fa-build", ] + def archive_examples(app: sphinx.application.Sphinx) -> None: """ Create a zip archive for each listed example included in the examples folder. From fff401595a658aa6a1920036029aa7e67208ba17 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 12:49:46 +0100 Subject: [PATCH 05/11] fix: add pdflatex to tox environment allowlist --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index e1baec64d..f1ba1f833 100644 --- a/tox.ini +++ b/tox.ini @@ -51,7 +51,7 @@ setenv = html,pdf: BUILDER_OPTS = --color -v -j auto --keep-going deps = -e .[doc] -allowlist_externals = make +allowlist_externals = pdflatex commands = html,pdf: sphinx-build -M "{env:BUILDER}" "{env:SOURCE_DIR}" "{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} pdf: pdflatex -interaction=nonstopmode -output-directory="{env:BUILD_DIR}/{env:BUILDER}" {env:BUILD_DIR}/{env:BUILDER}/*.tex \ No newline at end of file From d7732fbe1f4e37b3e0bddb44566ae143792d4522 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 13:00:51 +0100 Subject: [PATCH 06/11] fix: output dirs and latex file name --- tox.ini | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index f1ba1f833..375152180 100644 --- a/tox.ini +++ b/tox.ini @@ -53,5 +53,5 @@ deps = -e .[doc] allowlist_externals = pdflatex commands = - html,pdf: sphinx-build -M "{env:BUILDER}" "{env:SOURCE_DIR}" "{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} - pdf: pdflatex -interaction=nonstopmode -output-directory="{env:BUILD_DIR}/{env:BUILDER}" {env:BUILD_DIR}/{env:BUILDER}/*.tex \ No newline at end of file + html,pdf: sphinx-build -M "{env:BUILDER}" "{env:SOURCE_DIR}" "{env:BUILD_DIR}" {env:BUILDER_OPTS} + pdf: pdflatex -interaction=nonstopmode -output-directory="{env:BUILD_DIR}/{env:BUILDER}" {env:BUILD_DIR}/{env:BUILDER}/ansys-hps-client.tex \ No newline at end of file From 6256c33672738f4efc2c57181fc534acfdf63f24 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 13:38:14 +0100 Subject: [PATCH 07/11] fix: use make and make.bat --- .github/workflows/ci_cd.yml | 2 +- doc/make.bat | 1 + tox.ini | 12 +++++++----- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index 56af44eab..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-html,doc-pdf + 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 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/tox.ini b/tox.ini index 375152180..ff39b1202 100644 --- a/tox.ini +++ b/tox.ini @@ -38,20 +38,22 @@ commands = pre-commit install pre-commit run --all-files --show-diff-on-failure -[testenv:doc-{html,pdf}] +[testenv:doc-{html,pdf}-{linux,windows}] description = Environment for html: html documentation generation pdf: pdf documentation generation +platform = linux: linux + windows: win32 setenv = SOURCE_DIR = doc/source BUILD_DIR = doc/_build html: BUILDER = html - pdf: BUILDER = latex + pdf: BUILDER = pdf html,pdf: BUILDER_OPTS = --color -v -j auto --keep-going deps = -e .[doc] -allowlist_externals = pdflatex +allowlist_externals = make commands = - html,pdf: sphinx-build -M "{env:BUILDER}" "{env:SOURCE_DIR}" "{env:BUILD_DIR}" {env:BUILDER_OPTS} - pdf: pdflatex -interaction=nonstopmode -output-directory="{env:BUILD_DIR}/{env:BUILDER}" {env:BUILD_DIR}/{env:BUILDER}/ansys-hps-client.tex \ 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 From 76410d832ba3b097ad830b037411d06de5cf64e2 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 13:43:21 +0100 Subject: [PATCH 08/11] fix: fontawesome errors --- doc/source/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index c118e6d4c..77704ab03 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -384,8 +384,6 @@ def prepare_jinja_env(jinja_env) -> None: # Configuration for Sphinx Design # ----------------------------------------------------------------------------- -sd_fontawesome_latex = True - suppress_warnings = [ "design.fa-build", ] From 3059a7030ae6983deed371b58763e82d5db5bf70 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 13:51:15 +0100 Subject: [PATCH 09/11] fix: update nightly.yml --- .github/workflows/nightly.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index fe80db970..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-html,doc-pdf + 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 From 71efdc286315534d87f821d087a87ce65a2cb357 Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 14:12:00 +0100 Subject: [PATCH 10/11] doc: cleanup and update documentation --- doc/source/contribute.rst | 9 ++++----- tox.ini | 4 +++- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 241502736..d73f5323e 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 ff39b1202..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] @@ -43,6 +43,8 @@ description = Environment for html: html documentation generation pdf: pdf documentation generation + linux: on linux + windows: on windows platform = linux: linux windows: win32 setenv = From dc1b611bd749affe0a25cf79d5b1e62502c3c1bc Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 25 Mar 2025 14:16:24 +0100 Subject: [PATCH 11/11] fix: vale suggestions --- doc/source/contribute.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index d73f5323e..e45efbfb6 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -120,10 +120,10 @@ For building documentation, you can manually run these commands: .. code:: bash - make -C doc html # for building documentation on linux + make -C doc html # for building documentation on Linux However, the recommended way of checking documentation integrity is to use -``tox``. For example, the following can be run on linux: +``tox``. For example, the following can be run on Linux: .. code:: bash