feat: Add Tox environment for documentation preview (#642)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Jorge Martinez <[email protected]>

Author: 3 people

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.

package.json

@@ -1,12 +1,11 @@
 {
     "name": "ansys_sphinx_theme",
     "repository": "https://github.com/ansys/ansys-sphinx-theme",
-
     "description": "",
     "main": "",
     "scripts": {
         "build": "echo 'No build step needed' "
     },
     "dependencies": {},
     "devDependencies": {}
-}
+}

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
+showcontent = true

tox.ini

@@ -3,7 +3,7 @@ description = Default tox environments list
 envlist =
     code-style
     doc-style
-    doc-{links,html,pdf,clean}
+    doc-{links,html,pdf,clean,serve}
     dist
 skip_missing_interpreters = true
 isolated_build = true
@@ -36,10 +36,12 @@ 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
+skip_install =
+    clean: true
 allowlist_externals =
-    pdflatex
+    pdf: pdflatex
 extras = doc
 setenv =
     SOURCE_DIR = doc/source
@@ -50,12 +52,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}/"
 
 [testenv:dist]
 description = Checks project distribution
 skip_install = true
 deps =
     build
 commands =
-    python -m build {toxinidir}
+    python -m build {toxinidir}