feat: Add Tox environment for documentation preview

doc/changelog.d/642.added.md

@@ -0,0 +1 @@
+feat: Add Tox environment for documentation preview

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
@@ -270,7 +271,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 = """

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-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.

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
@@ -36,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
@@ -50,12 +54,13 @@ 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}"
+    serve: stb serve "{toxinidir}/{env:SOURCE_DIR}" --open-browser
 
 [testenv:dist]
 description = Checks project distribution
 skip_install = true
 deps =
     build
 commands =
-    python -m build {toxinidir}
+    python -m build {toxinidir}