feat: add documentation build environment to tox.ini

tox.ini

@@ -115,4 +115,48 @@ deps =
     -r requirements/requirements_test.txt
 
 commands =
-    pytest {env:PYTEST_PYTHON_FILES} {env:DEBUG} {env:COVERAGE} {env:RERUNS} {env:JUNITXML}
+    pytest {env:PYTEST_PYTHON_FILES} {env:DEBUG} {env:COVERAGE} {env:RERUNS} {env:JUNITXML}
+
+[testenv:doc-html]
+description = Generate html documentation
+
+setenv =
+    SOURCE_DIR = doc/source
+    BUILD_DIR = doc/build
+    BUILDER = html
+    BUILDER_OPTS = --color -j auto
+
+deps =
+    -r requirements/requirements_docs.txt
+
+commands =
+    # Ensure vtk compatibility
+    python -m pip uninstall --yes vtk
+    python -m pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==9.2.20230527.dev0
+
+    # Remove previously rendered documentation
+    python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
+
+    # Clean files from previous build
+    python -c "\
+    from os.path import exists; import shutil; \
+    [(shutil.rmtree(p) if exists(p) else None) for p in ['build', '{env:SOURCE_DIR}/images/auto-generated']]; \
+    [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    [('{env:SOURCE_DIR}/examples/07-python-operators/plugins', '{env:SOURCE_DIR}/_temp/plugins'), \
+    ('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress', '{env:SOURCE_DIR}/_temp/04_advanced'), \
+    ('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results', '{env:SOURCE_DIR}/_temp/12_fluids')]]; \
+    [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/examples'] if exists(p)]; \
+    [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    [('{env:SOURCE_DIR}/_temp/plugins', '{env:SOURCE_DIR}/examples/07-python-operators/plugins'), \
+    ('{env:SOURCE_DIR}/_temp/04_advanced', '{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress'), \
+    ('{env:SOURCE_DIR}/_temp/12_fluids', '{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results')]]; \
+    [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/_temp'] if exists(p)]"
+
+    # Build documentation
+    sphinx-build -b {env:BUILDER} {env:SOURCE_DIR} {env:BUILD_DIR}/{env:BUILDER} {env:BUILDER_OPTS}
+
+    # Patch pyVista issue with elemental plots by copying necessary images
+    python -c "\
+    import os, shutil, glob; os.makedirs('build/html/_images', exist_ok=True); \
+    [(shutil.copy(src, 'build/html/_images') if os.path.exists(src) else print(f'Source not found: {src}')) for src in \
+    glob.glob('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress/*') + glob.glob('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results/*')]"