feat: add documentation build environment to tox.ini (#2015)

* feat: changes implemented

* feat: add clean and link environment

* feat: server mgmt steps,syntax corrections

* feat: modified environment description

Author: moe-ad

tox.ini

@@ -109,10 +109,69 @@ deps =
 commands =
     pytest {env:PYTEST_PYTHON_FILES} {env:DEBUG} {env:COVERAGE} {env:RERUNS} {env:JUNITXML}
 
+[testenv:doc-{clean,links,html}]
+description = Environment for documentation generation
+
+setenv =
+    SOURCE_DIR = doc/source
+    BUILD_DIR = doc/build
+    BUILDER_OPTS = --color -j auto
+    links: BUILDER = linkcheck
+    html: BUILDER = html
+
+skip_install =
+    clean: True
+
+deps =
+    links,html: -r requirements/requirements_docs.txt
+
+commands_pre =
+    # Clear any running servers that may be locking resources
+    html,links: python -c "import psutil; proc_name = 'Ans.Dpf.Grpc'; nb_procs = len([proc.kill() for proc in psutil.process_iter() if proc_name in proc.name()]); \
+    html,links: print(f'Killed \{nb_procs} \{proc_name} processes.')"
+
+commands =
+    # Remove previously rendered documentation
+    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
+
+    # Ensure vtk compatibility
+    html: python -m pip uninstall --yes vtk
+    html: python -m pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==9.2.20230527.dev0
+
+    # Clean files from previous build
+    html: python -c "\
+    html: from os.path import exists; import shutil; \
+    html: [(shutil.rmtree(p) if exists(p) else None) for p in ['{env:SOURCE_DIR}/images/auto-generated']]; \
+    html: [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    html: [('{env:SOURCE_DIR}/examples/07-python-operators/plugins', '{env:SOURCE_DIR}/_temp/plugins'), \
+    html: ('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress', '{env:SOURCE_DIR}/_temp/04_advanced'), \
+    html: ('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results', '{env:SOURCE_DIR}/_temp/12_fluids')]]; \
+    html: [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/examples'] if exists(p)]; \
+    html: [(shutil.move(src, dst) if exists(src) else None) for src, dst in \
+    html: [('{env:SOURCE_DIR}/_temp/plugins', '{env:SOURCE_DIR}/examples/07-python-operators/plugins'), \
+    html: ('{env:SOURCE_DIR}/_temp/04_advanced', '{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress'), \
+    html: ('{env:SOURCE_DIR}/_temp/12_fluids', '{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results')]]; \
+    html: [shutil.rmtree(p) for p in ['{env:SOURCE_DIR}/_temp'] if exists(p)]"
+
+    # Build documentation
+    html,links: 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
+    html: python -c "\
+    html: import os, shutil, glob; os.makedirs('build/html/_images', exist_ok=True); \
+    html: [(shutil.copy(src, 'build/html/_images') if os.path.exists(src) else print(f'Source not found: {src}')) for src in \
+    html: glob.glob('{env:SOURCE_DIR}/examples/04-advanced/02-volume_averaged_stress/*') + glob.glob('{env:SOURCE_DIR}/examples/12-fluids/02-fluids_results/*')]"
+
+
+commands_post =
+    # Clear any running servers that may be locking resources
+    html,links: python -c "import psutil; proc_name = 'Ans.Dpf.Grpc'; nb_procs = len([proc.kill() for proc in psutil.process_iter() if proc_name in proc.name()]); \
+    html,links: print(f'Killed \{nb_procs} \{proc_name} processes.')"
+
 [testenv:build-wheel]
 description = Environment for custom build of package wheels
 
 skip_install = True
 
 commands = 
-    python .ci/build_wheel.py -p {posargs:{on_platform}} -w
+    python .ci/build_wheel.py -p {posargs:{on_platform}} -w