feat: improve contribute section documentation

doc/source/conf.py

@@ -1,6 +1,8 @@
 from datetime import datetime
 from glob import glob
 import os
+from pathlib import Path
+import subprocess
 
 from ansys_sphinx_theme import (
     ansys_favicon,
@@ -109,9 +111,8 @@
     "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_design",
-    "sphinx_gallery.gen_gallery",
+    "sphinx_jinja",
     'sphinx_reredirects',
-    "ansys_sphinx_theme.extension.autoapi",
 ]
 
 redirects = {
@@ -373,4 +374,34 @@ def reset_servers(gallery_conf, fname, when):
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
+epub_exclude_files = ["search.html"]
+
+# Common content for every RST file such us links
+rst_epilog = ""
+links_filepath = Path(__file__).parent.absolute() / "links.rst"
+rst_epilog += links_filepath.read_text(encoding="utf-8")
+
+jinja_globals = {
+    "PYDPF_CORE_VERSION": version,
+}
+
+# Get list of tox environments and add to jinja context
+envs = subprocess.run(["tox", "list", "-q"], capture_output=True, text=True).stdout.splitlines()
+envs.remove("default environments:")
+envs.remove("additional environments:")
+envs.remove("")
+
+jinja_contexts = {
+    "toxenvs" : {
+        "envs": envs,
+    }
+}
+
+# Optionally exclude api or example documentation generation.
+BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
+if BUILD_API:
+    extensions.extend(["ansys_sphinx_theme.extension.autoapi"])
+
+BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
+if BUILD_EXAMPLES:
+    extensions.extend(["sphinx_gallery.gen_gallery"])

doc/source/dpf_ansys_file_support_table.rst

@@ -4,30 +4,30 @@
    :widths: auto
    :align: center
 
-+--------------------+------------------------+----------------------------------+----------------------------------+
-|     **Solver**     |    **File format**     |       **Server version**         |       **DPF examples**           |
-+====================+========================+==================================+==================================+
-|                    | .rst, .mode, .rth      | **1.0** and later                | :ref:`ref_basic_example`         |
-|        MAPDL       | .rfrq, .rdsp           | (*Ansys 2021 R1*)                |                                  |
-|                    +------------------------+----------------------------------+----------------------------------+
-|                    | .psd, .prs             | **10.0** and later               |                                  |
-|                    |                        | (*Ansys 2025 R2 pre0*)           |                                  |
-+--------------------+------------------------+----------------------------------+----------------------------------+
-|       LS DYNA      | .d3plot, .binout       | **4.0** and later                | :ref:`examples_lsdyna`           |
-|                    |                        | (*Ansys 2022 R2*)                |                                  |
-+--------------------+------------------------+----------------------------------+----------------------------------+
-|                    | *CFF restart files*    |                                  | :ref:`ref_fluids_model`          |
-|                    | .cas/dat.h5            |                                  +----------------------------------+
-|                    |                        | **7.0** and later                | :ref:`ref_fluids_mesh`           |
-|        Fluent      +------------------------+ (*Ansys 2024 R1 pre0*)           +----------------------------------+
-|                    | *Project files*        |                                  | :ref:`ref_fluids_results`        |
-|                    | .flprj                 |                                  |                                  |
-+--------------------+------------------------+----------------------------------+----------------------------------+
-|                    | *CFF files*            |                                  | :ref:`examples_cfx`              |
-|                    | .cas/dat.cff           |                                  +----------------------------------+
-|                    | .res                   | **7.0** and later                | :ref:`ref_fluids_model`          |
-|          CFX       +------------------------+ (*Ansys 2024 R1 pre0*)           +----------------------------------+
-|                    | *Project files*        |                                  | :ref:`ref_fluids_mesh`           |
-|                    | .flprj                 |                                  +----------------------------------+
-|                    |                        |                                  | :ref:`ref_fluids_results`        |
-+--------------------+------------------------+----------------------------------+----------------------------------+
+   +--------------------+------------------------+----------------------------------+----------------------------------+
+   |     **Solver**     |    **File format**     |       **Server version**         |       **DPF examples**           |
+   +====================+========================+==================================+==================================+
+   |                    | .rst, .mode, .rth      | **1.0** and later                | :ref:`ref_basic_example`         |
+   |        MAPDL       | .rfrq, .rdsp           | (*Ansys 2021 R1*)                |                                  |
+   |                    +------------------------+----------------------------------+----------------------------------+
+   |                    | .psd, .prs             | **10.0** and later               |                                  |
+   |                    |                        | (*Ansys 2025 R2 pre0*)           |                                  |
+   +--------------------+------------------------+----------------------------------+----------------------------------+
+   |       LS DYNA      | .d3plot, .binout       | **4.0** and later                | :ref:`examples_lsdyna`           |
+   |                    |                        | (*Ansys 2022 R2*)                |                                  |
+   +--------------------+------------------------+----------------------------------+----------------------------------+
+   |                    | *CFF restart files*    |                                  | :ref:`ref_fluids_model`          |
+   |                    | .cas/dat.h5            |                                  +----------------------------------+
+   |                    |                        | **7.0** and later                | :ref:`ref_fluids_mesh`           |
+   |        Fluent      +------------------------+ (*Ansys 2024 R1 pre0*)           +----------------------------------+
+   |                    | *Project files*        |                                  | :ref:`ref_fluids_results`        |
+   |                    | .flprj                 |                                  |                                  |
+   +--------------------+------------------------+----------------------------------+----------------------------------+
+   |                    | *CFF files*            |                                  | :ref:`examples_cfx`              |
+   |                    | .cas/dat.cff           |                                  +----------------------------------+
+   |                    | .res                   | **7.0** and later                | :ref:`ref_fluids_model`          |
+   |          CFX       +------------------------+ (*Ansys 2024 R1 pre0*)           +----------------------------------+
+   |                    | *Project files*        |                                  | :ref:`ref_fluids_mesh`           |
+   |                    | .flprj                 |                                  +----------------------------------+
+   |                    |                        |                                  | :ref:`ref_fluids_results`        |
+   +--------------------+------------------------+----------------------------------+----------------------------------+

doc/source/getting_started/contribute/developer.rst

@@ -0,0 +1,266 @@
+Contributing as a developer
+###########################
+
+.. grid:: 1 2 3 3
+    :padding: 2 2 2 2
+
+    .. grid-item-card:: :fa:`download` Clone the repository
+        :link: clone-the-repository
+        :link-type: ref
+
+        Download your own copy in your local machine.
+
+    .. grid-item-card:: :fa:`download` Install for developers
+        :link: install-for-developers
+        :link-type: ref
+
+        Install the project in editable mode.
+
+    .. grid-item-card:: :fa:`vial-circle-check` Run the tests
+        :link: run-tests
+        :link-type: ref
+
+        Verify your changes by testing the project.
+
+
+.. _clone-the-repository:
+
+Clone the repository
+====================
+
+Clone the latest version of PyDPF-Core in
+development mode by running this code:
+
+.. code-block:: bash
+
+    git clone https://github.com/ansys/pydpf-core
+
+.. _install-for-developers:
+
+Install for developers
+======================
+
+Installing PyDPF-Core in development mode allows you to perform changes to the code
+and see the changes reflected in your environment without having to reinstall
+the library every time you make a change.
+
+Virtual environment
+-------------------
+
+Start by navigating to the project's root directory by running:
+
+.. code-block:: bash
+
+    cd pydpf-core
+
+Then, create a new virtual environment named ``.venv`` to isolate your system's
+Python environment by running:
+
+.. code-block:: bash
+
+    python -m venv .venv
+
+Finally, activate this environment by running:
+
+.. tab-set::
+
+    .. tab-item:: Windows
+
+        .. tab-set::
+
+            .. tab-item:: CMD
+
+                .. code-block:: bash
+
+                    .venv\Scripts\activate.bat
+
+            .. tab-item:: PowerShell
+
+                .. code-block:: text
+
+                    .venv\Scripts\Activate.ps1
+
+    .. tab-item:: macOS/Linux/UNIX
+
+        .. code-block:: text
+
+            source .venv/bin/activate
+
+Development mode
+----------------
+
+Now, install PyDPF-Core in editable mode by running:
+
+.. code-block:: text
+
+    python -m pip install --editable .
+
+Verify the installation by checking the version of the library:
+
+
+.. code-block:: python
+
+    from ansys.dpf.core import __version__
+
+
+    print(f"PyDPF-Core version is {__version__}")
+
+.. jinja::
+
+    .. code-block:: bash
+
+       >>> PyDPF-Core version is {{ PYDPF_CORE_VERSION }}
+
+Install Tox
+-----------
+
+Once the project is installed, you can install `Tox`_. This is a cross-platform
+automation tool. The main advantage of Tox is that it eases routine tasks like project
+testing, documentation generation, and wheel building in separate and isolated Python
+virtual environments. To install Tox, run:
+
+.. code-block:: text
+
+    python -m pip install tox tox-uv
+
+Finally, verify the installation by listing all the different environments
+(automation rules) for PyDPF-Core:
+
+.. code-block:: text
+
+    python -m tox list
+
+.. jinja:: toxenvs
+
+    .. dropdown:: Default Tox environments
+        :animate: fade-in
+        :icon: three-bars
+
+        .. list-table::
+            :header-rows: 1
+            :widths: auto
+
+            * - Environment
+              - Description
+            {% for environment in envs %}
+            {% set name, description  = environment.split("->") %}
+            * - {{ name }}
+              - {{ description }}
+            {% endfor %}
+
+.. _run-tests:
+
+Run the tests
+=============
+
+Once you have made your changes, you can run the tests to verify that your
+modifications did not break the project. PyDPF-Core tests are organized into groups and require additional steps
+during execution to ensure tests run as expected without errors, therefore, PyDPF-Core tox configuration
+supports different markers to account for this. These markers are associated with a
+dedicated `Tox`_ environment. To also allow flexibity required during development, different DPF Server installation
+can also be used as explained in the subsections that follow.
+
+Unified DPF Server installation or specific DPF Server installation using ANSYS_DPF_PATH environment variable
+-------------------------------------------------------------------------------------------------------------
+
+These two installation DPF Server installation methods i.e. (unified or via ANSYS_DPF_PATH) require no special handling.
+Individual test groups can be simply run with the following commands:
+
+.. jinja:: toxenvs
+
+    .. dropdown:: Testing individual groups
+        :animate: fade-in
+        :icon: three-bars
+
+        .. list-table::
+            :header-rows: 1
+            :widths: auto
+
+            * - Environment
+              - Command
+            {% for environment in envs %}
+            {% set name, description  = environment.split("->") %}
+            {% if name.startswith("test-")%}
+            * - {{ name }}
+              - python -m tox -e pretest,{{ name }},posttest,kill-servers
+            {% endif %}
+            {% endfor %}
+
+Multiple tests can be run in different ways by specifying appropriate tox command:
+
+.. dropdown:: Testing more than one group sequentially
+    :animate: fade-in
+    :icon: three-bars
+
+    .. list-table::
+        :header-rows: 1
+        :widths: auto
+
+        * - Command
+          - Description
+        * - python -m tox
+          - Run all test groups sequentially
+        * - python -m tox -e pretest,test-api,test-launcher,posttest,kill-servers
+          - run specific selection of tests sequentially
+
+To save testing time, the ``--parallel`` flag can be passed when running multiple environments at once.
+Some test groups are incompatible for parallel runs by nature of their configuration. Some labels have
+been added to the tox configuration for compatible tests to make running them easier.
+The following commands are thus recommended when you wish to take advantage of parallel runs.
+
+.. dropdown:: Testing more than one group in parallel
+    :animate: fade-in
+    :icon: three-bars
+
+    .. list-table::
+        :header-rows: 1
+        :widths: auto
+
+        * - Command
+          - Description
+        * - python -m tox -m localparalleltests --parallel
+          - Run all compatible test groups in parallel
+        * - python -m tox -e othertests
+          - Run incompatible test groups sequentially
+        * - python -m pretest,test-api,test-launcher,posttest,kill-servers --parallel
+          - Run specific selection of tests in parallel
+
+Standalone DPF Server installation
+----------------------------------
+Standalone DPF Server is usually `installed in editable mode <https://dpf.docs.pyansys.com/version/dev/getting_started/dpf_server.html#install-dpf-server>`_.
+Accordingly, tox commands need to be adjusted for installation of standalone DPF Server in the isolated python environments
+tox creates to run these tests in. This is achieved by adding ``-x testenv.deps+="-e <path/to/dpf/standalone>"``
+to any of the previous tox commands.
+
+For example, to run compatible parallel tests while using a Standalone DPF Server whose path is ``ansys_dpf_server_lin_v2025.1.pre0``, simply run:
+
+.. code-block:: bash
+
+    python -m tox -m localparalleltests --parallel -x testenv.deps+="-e ansys_dpf_server_lin_v2025.1.pre0"
+
+.. warning::
+    When the ANSYS_DPF_PATH environment variable is set, the server pointed to
+    `takes precedence <https://dpf.docs.pyansys.com/version/dev/getting_started/dpf_server.html#manage-multiple-dpf-server-installations>`_
+    over any other DPF Server installation method. Therefore, a standalone DPF Server installed in editable mode, in the
+    presence of ANSYS_DPF_PATH environment variable, will be ignored.
+
+    With tox, a simple workaround is not setting this environment variable at the operating system level but passing it explicitly only when
+    required. This is achived by adding ``-x testenv.setenv+="ANSYS_DPF_PATH=<path/to/valid/DPF/Server/installation>"`` to any tox command.
+
+    Alternatively, when set at the operating system level, commenting out the line where this environment variable is passed in the tox
+    configuration file will ensure that it is ignored within the tox environments.
+
+    .. image:: tox.png
+
+Testing on Linux via WSL
+------------------------
+Some system dependencies required for VTK to run properly might be missing when running tests on linux via WSL (or even linux in general). 
+The identified workaround for this is to install the OSMesa wheel variant that leverages offscreen rendering with OSMesa.
+This wheel is being built for both Linux and Windows at this time and bundles all of the necessary libraries into the wheel. This is
+achieved by adding ``-x testenv.commands_pre="uv pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==<version>"``
+
+For example, to run all tests sequentially on linux, while using a Standalone DPF Server whose path is ``ansys_dpf_server_lin_v2025.1.pre0``, simply run:
+
+.. code-block:: text
+
+    python -m tox --parallel -x testenv.deps+="-e ansys_dpf_server_lin_v2025.1.pre0" -x testenv.commands_pre="uv pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==9.2.20230527.dev0"