From 54de8384125a6d1a43be7fa05eb9de4c5c2932c8 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 6 Mar 2025 10:15:06 +0100 Subject: [PATCH 1/7] feat: add docs preview to tox env --- tox.ini | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index 944ebf4ba..7e7d5b020 100644 --- a/tox.ini +++ b/tox.ini @@ -4,6 +4,7 @@ envlist = code-style doc-style doc-{links,html,pdf,clean} + doc-preview dist skip_missing_interpreters = true isolated_build = true @@ -50,7 +51,7 @@ setenv = links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going commands = links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} - clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" + clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" [testenv:dist] description = Checks project distribution @@ -58,4 +59,15 @@ skip_install = true deps = build commands = - python -m build {toxinidir} \ No newline at end of file + python -m build {toxinidir} + +[testenv:doc-preview] +description = Build and serve documentation locally +allowlist_externals = + stb +extras = doc, "sphinx-theme-builder[cli]" +setenv = + SOURCE_DIR = doc/source + BUILD_DIR = doc/_build +commands = + stb serve "{toxinidir}/{env:SOURCE_DIR}" --open-browser \ No newline at end of file From 21a86f086c50e3505610819df30d521f20608efe Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 6 Mar 2025 10:56:19 +0100 Subject: [PATCH 2/7] feat: add docs config an extra deps --- doc/source/conf.py | 6 ++++-- doc/source/contribute/developer.rst | 6 ++++++ tox.ini | 4 +++- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 66ca024d4..95f21dcae 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,6 +26,7 @@ ) THIS_PATH = Path(__file__).parent.resolve() +PYANSYS_LIGHT_SQUARE = (THIS_PATH / "_static" / "pyansys_light_square.png").resolve() EXAMPLE_PATH = (THIS_PATH / "examples" / "sphinx_examples").resolve() # Project information @@ -191,7 +192,8 @@ def extract_example_links( list List of example links. """ - g = Github() + token = os.getenv("GITHUB_TOKEN") + g = Github(token) repo = g.get_repo(repo_fullname) contents = repo.get_contents(path_relative_to_root) if not isinstance(contents, list): @@ -270,7 +272,7 @@ def download_and_process_files(example_links: List[str]) -> List[str]: "download_all_examples": False, # Modules for which function level galleries are created. In "image_scrapers": ("pyvista", "matplotlib"), - "default_thumb_file": "source/_static/pyansys_light_square.png", + "default_thumb_file": str(PYANSYS_LIGHT_SQUARE), } nbsphinx_prolog = """ diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 47f83eb06..6d147c49d 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -239,3 +239,9 @@ You can clean the build directory by running:: # On Windows doc\make.bat clean + +.. Note:: + + Use ``tox -e doc-preview`` to build the documentation and open it in your + default browser. This command will also watch for changes in the source + files and rebuild the documentation automatically. \ No newline at end of file diff --git a/tox.ini b/tox.ini index 7e7d5b020..1728af63e 100644 --- a/tox.ini +++ b/tox.ini @@ -65,7 +65,9 @@ commands = description = Build and serve documentation locally allowlist_externals = stb -extras = doc, "sphinx-theme-builder[cli]" +extras = doc +deps = + sphinx-theme-builder[cli] @ https://github.com/pradyunsg/sphinx-theme-builder/archive/d9f620b1a73839728c95b596343595d3952ec8bf.zip setenv = SOURCE_DIR = doc/source BUILD_DIR = doc/_build From 373e789df77ef4453724cbc11d13655021c95fed Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 6 Mar 2025 10:57:27 +0100 Subject: [PATCH 3/7] fix: revert changes --- doc/source/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 95f21dcae..f36dc533f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -192,8 +192,7 @@ def extract_example_links( list List of example links. """ - token = os.getenv("GITHUB_TOKEN") - g = Github(token) + g = Github() repo = g.get_repo(repo_fullname) contents = repo.get_contents(path_relative_to_root) if not isinstance(contents, list): From 5c328d43f034bec456f6b679c7db561e56e5c54f Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Thu, 6 Mar 2025 10:01:24 +0000 Subject: [PATCH 4/7] chore: adding changelog file 642.added.md [dependabot-skip] --- doc/changelog.d/642.added.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/642.added.md diff --git a/doc/changelog.d/642.added.md b/doc/changelog.d/642.added.md new file mode 100644 index 000000000..a9d06a30c --- /dev/null +++ b/doc/changelog.d/642.added.md @@ -0,0 +1 @@ +feat: Add Tox environment for documentation preview \ No newline at end of file From 187566e18cdd959049de3ac102956cec1447cf96 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 6 Mar 2025 14:43:32 +0100 Subject: [PATCH 5/7] fix: tox file --- doc/source/contribute/developer.rst | 2 +- tox.ini | 21 ++++++--------------- 2 files changed, 7 insertions(+), 16 deletions(-) diff --git a/doc/source/contribute/developer.rst b/doc/source/contribute/developer.rst index 6d147c49d..a687e10b0 100644 --- a/doc/source/contribute/developer.rst +++ b/doc/source/contribute/developer.rst @@ -242,6 +242,6 @@ You can clean the build directory by running:: .. Note:: - Use ``tox -e doc-preview`` to build the documentation and open it in your + Use ``tox -e doc-serve`` to build the documentation and open it in your default browser. This command will also watch for changes in the source files and rebuild the documentation automatically. \ No newline at end of file diff --git a/tox.ini b/tox.ini index 1728af63e..ae4384ad2 100644 --- a/tox.ini +++ b/tox.ini @@ -37,10 +37,13 @@ commands = vale sync --config="{toxinidir}/doc/.vale.ini" vale --config="{toxinidir}/doc/.vale.ini" "{toxinidir}/doc" -[testenv:doc-{clean,links,html,pdf}] +[testenv:doc-{clean,links,html,pdf,serve}] description = Checks documentation links and pages generates properly +deps= + serve: sphinx-theme-builder[cli] @ https://github.com/pradyunsg/sphinx-theme-builder/archive/d9f620b1a73839728c95b596343595d3952ec8bf.zip allowlist_externals = - pdflatex + pdf: pdflatex + serve: stb extras = doc setenv = SOURCE_DIR = doc/source @@ -52,6 +55,7 @@ setenv = commands = links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" + serve: stb serve "{toxinidir}/{env:SOURCE_DIR}" --open-browser [testenv:dist] description = Checks project distribution @@ -60,16 +64,3 @@ deps = build commands = python -m build {toxinidir} - -[testenv:doc-preview] -description = Build and serve documentation locally -allowlist_externals = - stb -extras = doc -deps = - sphinx-theme-builder[cli] @ https://github.com/pradyunsg/sphinx-theme-builder/archive/d9f620b1a73839728c95b596343595d3952ec8bf.zip -setenv = - SOURCE_DIR = doc/source - BUILD_DIR = doc/_build -commands = - stb serve "{toxinidir}/{env:SOURCE_DIR}" --open-browser \ No newline at end of file From d378008d247c5ec81867c599a5521d4e37292589 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Thu, 6 Mar 2025 16:23:32 +0100 Subject: [PATCH 6/7] fix(tox): ensure stb is installed --- package.json | 3 +-- pyproject.toml | 5 +++-- tox.ini | 7 +++---- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/package.json b/package.json index 893d26ffb..fc3d67b81 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,6 @@ { "name": "ansys_sphinx_theme", "repository": "https://github.com/ansys/ansys-sphinx-theme", - "description": "", "main": "", "scripts": { @@ -9,4 +8,4 @@ }, "dependencies": {}, "devDependencies": {} -} \ No newline at end of file +} diff --git a/pyproject.toml b/pyproject.toml index 91aba3f76..45109168f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [build-system] requires = [ - "sphinx-theme-builder >= 0.2.0b2,<1", + "sphinx-theme-builder>=0.2.0b2,<1", ] build-backend = "sphinx_theme_builder" @@ -62,6 +62,7 @@ doc = [ "sphinx-jinja==2.0.2", "sphinx-notfound-page==1.1.0", "tox==4.24.1", + "sphinx-theme-builder[cli]==0.2.0b2", ] changelog = [ "PyYAML==6.0.2", @@ -163,4 +164,4 @@ showcontent = true [[tool.towncrier.type]] directory = "miscellaneous" name = "Miscellaneous" -showcontent = true \ No newline at end of file +showcontent = true diff --git a/tox.ini b/tox.ini index ae4384ad2..08a847b5b 100644 --- a/tox.ini +++ b/tox.ini @@ -39,11 +39,10 @@ commands = [testenv:doc-{clean,links,html,pdf,serve}] description = Checks documentation links and pages generates properly -deps= - serve: sphinx-theme-builder[cli] @ https://github.com/pradyunsg/sphinx-theme-builder/archive/d9f620b1a73839728c95b596343595d3952ec8bf.zip +skip_install = + clean: true allowlist_externals = pdf: pdflatex - serve: stb extras = doc setenv = SOURCE_DIR = doc/source @@ -55,7 +54,7 @@ setenv = commands = links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER} clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}" - serve: stb serve "{toxinidir}/{env:SOURCE_DIR}" --open-browser + serve: stb serve "{toxinidir}/{env:SOURCE_DIR}/" [testenv:dist] description = Checks project distribution From e9542cf2d16b8782374f3e3f8be20a3c9eb5f887 Mon Sep 17 00:00:00 2001 From: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> Date: Thu, 6 Mar 2025 16:28:28 +0100 Subject: [PATCH 7/7] Apply suggestions from code review --- tox.ini | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index 08a847b5b..3524367b7 100644 --- a/tox.ini +++ b/tox.ini @@ -3,8 +3,7 @@ description = Default tox environments list envlist = code-style doc-style - doc-{links,html,pdf,clean} - doc-preview + doc-{links,html,pdf,clean,serve} dist skip_missing_interpreters = true isolated_build = true