Skip to content

Commit 19ac25a

Browse files
moe-adRevathyvenugopal162
moe-ad
and
Revathyvenugopal162
authored
feat: improve contribute section documentation (#2085)
* feat: improve contribute documentation * feat: source files added * feat: adjustments to user.rst * feat: adjustments to documentarian.rst file * feat: corrections * feat: added convenant code of conduct admonition * feat: apply suggestions from Revathy's review Co-authored-by: Revathy Venugopal <[email protected]> * feat: corrections * feat: apply suggestions from Revathy's review Co-authored-by: Revathy Venugopal <[email protected]> * feat: apply suggestions from Revathy's review Co-authored-by: Revathy Venugopal <[email protected]> * feat: review suggestion correction plus pypandoc(#1944) * feat: apply suggestions from Revathy's review Co-authored-by: Revathy Venugopal <[email protected]> --------- Co-authored-by: Revathy Venugopal <[email protected]>
1 parent 05c565c commit 19ac25a

File tree

10 files changed

+782
-58
lines changed

10 files changed

+782
-58
lines changed

‎doc/source/conf.py‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
from datetime import datetime
22
from glob import glob
33
import os
4+
from pathlib import Path
5+
import subprocess
46

57
from ansys_sphinx_theme import (
68
ansys_favicon,
@@ -109,9 +111,8 @@
109111
"sphinx.ext.todo",
110112
"sphinx_copybutton",
111113
"sphinx_design",
112-
"sphinx_gallery.gen_gallery",
114+
"sphinx_jinja",
113115
'sphinx_reredirects',
114-
"ansys_sphinx_theme.extension.autoapi",
115116
]
116117

117118
redirects = {
@@ -373,4 +374,34 @@ def reset_servers(gallery_conf, fname, when):
373374
# epub_uid = ''
374375

375376
# A list of files that should not be packed into the epub file.
376-
epub_exclude_files = ["search.html"]
377+
epub_exclude_files = ["search.html"]
378+
379+
# Common content for every RST file such us links
380+
rst_epilog = ""
381+
links_filepath = Path(__file__).parent.absolute() / "links.rst"
382+
rst_epilog += links_filepath.read_text(encoding="utf-8")
383+
384+
jinja_globals = {
385+
"PYDPF_CORE_VERSION": version,
386+
}
387+
388+
# Get list of tox environments and add to jinja context
389+
envs = subprocess.run(["tox", "list", "-q"], capture_output=True, text=True).stdout.splitlines()
390+
envs.remove("default environments:")
391+
envs.remove("additional environments:")
392+
envs.remove("")
393+
394+
jinja_contexts = {
395+
"toxenvs" : {
396+
"envs": envs,
397+
}
398+
}
399+
400+
# Optionally exclude api or example documentation generation.
401+
BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
402+
if BUILD_API:
403+
extensions.extend(["ansys_sphinx_theme.extension.autoapi"])
404+
405+
BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
406+
if BUILD_EXAMPLES:
407+
extensions.extend(["sphinx_gallery.gen_gallery"])

‎doc/source/dpf_ansys_file_support_table.rst‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,30 @@
44
:widths: auto
55
:align: center
66

7-
+--------------------+------------------------+----------------------------------+----------------------------------+
8-
| **Solver** | **File format** | **Server version** | **DPF examples** |
9-
+====================+========================+==================================+==================================+
10-
| | .rst, .mode, .rth | **1.0** and later | :ref:`ref_basic_example` |
11-
| MAPDL | .rfrq, .rdsp | (*Ansys 2021 R1*) | |
12-
| +------------------------+----------------------------------+----------------------------------+
13-
| | .psd, .prs | **10.0** and later | |
14-
| | | (*Ansys 2025 R2 pre0*) | |
15-
+--------------------+------------------------+----------------------------------+----------------------------------+
16-
| LS DYNA | .d3plot, .binout | **4.0** and later | :ref:`examples_lsdyna` |
17-
| | | (*Ansys 2022 R2*) | |
18-
+--------------------+------------------------+----------------------------------+----------------------------------+
19-
| | *CFF restart files* | | :ref:`ref_fluids_model` |
20-
| | .cas/dat.h5 | +----------------------------------+
21-
| | | **7.0** and later | :ref:`ref_fluids_mesh` |
22-
| Fluent +------------------------+ (*Ansys 2024 R1 pre0*) +----------------------------------+
23-
| | *Project files* | | :ref:`ref_fluids_results` |
24-
| | .flprj | | |
25-
+--------------------+------------------------+----------------------------------+----------------------------------+
26-
| | *CFF files* | | :ref:`examples_cfx` |
27-
| | .cas/dat.cff | +----------------------------------+
28-
| | .res | **7.0** and later | :ref:`ref_fluids_model` |
29-
| CFX +------------------------+ (*Ansys 2024 R1 pre0*) +----------------------------------+
30-
| | *Project files* | | :ref:`ref_fluids_mesh` |
31-
| | .flprj | +----------------------------------+
32-
| | | | :ref:`ref_fluids_results` |
33-
+--------------------+------------------------+----------------------------------+----------------------------------+
7+
+--------------------+------------------------+----------------------------------+----------------------------------+
8+
| **Solver** | **File format** | **Server version** | **DPF examples** |
9+
+====================+========================+==================================+==================================+
10+
| | .rst, .mode, .rth | **1.0** and later | :ref:`ref_basic_example` |
11+
| MAPDL | .rfrq, .rdsp | (*Ansys 2021 R1*) | |
12+
| +------------------------+----------------------------------+----------------------------------+
13+
| | .psd, .prs | **10.0** and later | |
14+
| | | (*Ansys 2025 R2 pre0*) | |
15+
+--------------------+------------------------+----------------------------------+----------------------------------+
16+
| LS DYNA | .d3plot, .binout | **4.0** and later | :ref:`examples_lsdyna` |
17+
| | | (*Ansys 2022 R2*) | |
18+
+--------------------+------------------------+----------------------------------+----------------------------------+
19+
| | *CFF restart files* | | :ref:`ref_fluids_model` |
20+
| | .cas/dat.h5 | +----------------------------------+
21+
| | | **7.0** and later | :ref:`ref_fluids_mesh` |
22+
| Fluent +------------------------+ (*Ansys 2024 R1 pre0*) +----------------------------------+
23+
| | *Project files* | | :ref:`ref_fluids_results` |
24+
| | .flprj | | |
25+
+--------------------+------------------------+----------------------------------+----------------------------------+
26+
| | *CFF files* | | :ref:`examples_cfx` |
27+
| | .cas/dat.cff | +----------------------------------+
28+
| | .res | **7.0** and later | :ref:`ref_fluids_model` |
29+
| CFX +------------------------+ (*Ansys 2024 R1 pre0*) +----------------------------------+
30+
| | *Project files* | | :ref:`ref_fluids_mesh` |
31+
| | .flprj | +----------------------------------+
32+
| | | | :ref:`ref_fluids_results` |
33+
+--------------------+------------------------+----------------------------------+----------------------------------+

‎doc/source/getting_started/contribute/developer.rst‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
Contributing as a developer
2+
###########################
3+
4+
.. grid:: 1 2 3 3
5+
:padding: 2 2 2 2
6+
7+
.. grid-item-card:: :fa:`download` Clone the repository
8+
:link: clone-the-repository
9+
:link-type: ref
10+
11+
Download your own copy in your local machine.
12+
13+
.. grid-item-card:: :fa:`download` Install for developers
14+
:link: install-for-developers
15+
:link-type: ref
16+
17+
Install the project in editable mode.
18+
19+
.. grid-item-card:: :fa:`vial-circle-check` Run the tests
20+
:link: run-tests
21+
:link-type: ref
22+
23+
Verify your changes by testing the project.
24+
25+
26+
.. _clone-the-repository:
27+
28+
Clone the repository
29+
====================
30+
31+
Clone the latest version of PyDPF-Core in
32+
development mode by running this code:
33+
34+
.. code-block:: bash
35+
36+
git clone https://github.com/ansys/pydpf-core
37+
38+
.. _install-for-developers:
39+
40+
Install for developers
41+
======================
42+
43+
Installing PyDPF-Core in development mode allows you to perform changes to the code
44+
and see the changes reflected in your environment without having to reinstall
45+
the library every time you make a change.
46+
47+
Virtual environment
48+
-------------------
49+
50+
Start by navigating to the project's root directory by running:
51+
52+
.. code-block:: bash
53+
54+
cd pydpf-core
55+
56+
Then, create a new virtual environment named ``.venv`` to isolate your system's
57+
Python environment by running:
58+
59+
.. code-block:: bash
60+
61+
python -m venv .venv
62+
63+
Finally, activate this environment by running:
64+
65+
.. tab-set::
66+
67+
.. tab-item:: Windows
68+
69+
.. tab-set::
70+
71+
.. tab-item:: CMD
72+
73+
.. code-block:: bash
74+
75+
.venv\Scripts\activate.bat
76+
77+
.. tab-item:: PowerShell
78+
79+
.. code-block:: text
80+
81+
.venv\Scripts\Activate.ps1
82+
83+
.. tab-item:: macOS/Linux/UNIX
84+
85+
.. code-block:: text
86+
87+
source .venv/bin/activate
88+
89+
Development mode
90+
----------------
91+
92+
Now, install PyDPF-Core in editable mode by running:
93+
94+
.. code-block:: text
95+
96+
python -m pip install --editable .
97+
98+
Verify the installation by checking the version of the library:
99+
100+
101+
.. code-block:: python
102+
103+
from ansys.dpf.core import __version__
104+
105+
106+
print(f"PyDPF-Core version is {__version__}")
107+
108+
.. jinja::
109+
110+
.. code-block:: bash
111+
112+
>>> PyDPF-Core version is {{ PYDPF_CORE_VERSION }}
113+
114+
Install Tox
115+
-----------
116+
117+
Once the project is installed, you can install `Tox`_. This is a cross-platform
118+
automation tool. The main advantage of Tox is that it eases routine tasks like project
119+
testing, documentation generation, and wheel building in separate and isolated Python
120+
virtual environments. To install Tox, run:
121+
122+
.. code-block:: text
123+
124+
python -m pip install tox tox-uv
125+
126+
Finally, verify the installation by listing all the different environments
127+
(automation rules) for PyDPF-Core:
128+
129+
.. code-block:: text
130+
131+
python -m tox list
132+
133+
.. jinja:: toxenvs
134+
135+
.. dropdown:: Default Tox environments
136+
:animate: fade-in
137+
:icon: three-bars
138+
139+
.. list-table::
140+
:header-rows: 1
141+
:widths: auto
142+
143+
* - Environment
144+
- Description
145+
{% for environment in envs %}
146+
{% set name, description = environment.split("->") %}
147+
* - {{ name }}
148+
- {{ description }}
149+
{% endfor %}
150+
151+
.. _run-tests:
152+
153+
Run the tests
154+
=============
155+
156+
Once you have made your changes, you can run the tests to verify that your
157+
modifications did not break the project. PyDPF-Core tests are organized into groups and require additional steps
158+
during execution to ensure tests run as expected without errors, therefore, PyDPF-Core tox configuration
159+
supports different markers to account for this. These markers are associated with a
160+
dedicated `Tox`_ environment. To also allow flexibity required during development, different DPF Server installation
161+
can also be used as explained in the subsections that follow.
162+
163+
Unified DPF Server installation or specific DPF Server installation using ANSYS_DPF_PATH environment variable
164+
-------------------------------------------------------------------------------------------------------------
165+
166+
These two installation DPF Server installation methods i.e. (unified or via ANSYS_DPF_PATH) require no special handling.
167+
Individual test groups can be simply run with the following commands:
168+
169+
.. jinja:: toxenvs
170+
171+
.. dropdown:: Testing individual groups
172+
:animate: fade-in
173+
:icon: three-bars
174+
175+
.. list-table::
176+
:header-rows: 1
177+
:widths: auto
178+
179+
* - Environment
180+
- Command
181+
{% for environment in envs %}
182+
{% set name, description = environment.split("->") %}
183+
{% if name.startswith("test-")%}
184+
* - {{ name }}
185+
- python -m tox -e pretest,{{ name }},posttest,kill-servers
186+
{% endif %}
187+
{% endfor %}
188+
189+
Multiple tests can be run in different ways by specifying appropriate tox command:
190+
191+
.. dropdown:: Testing more than one group sequentially
192+
:animate: fade-in
193+
:icon: three-bars
194+
195+
.. list-table::
196+
:header-rows: 1
197+
:widths: auto
198+
199+
* - Command
200+
- Description
201+
* - python -m tox
202+
- Run all test groups sequentially
203+
* - python -m tox -e pretest,test-api,test-launcher,posttest,kill-servers
204+
- run specific selection of tests sequentially
205+
206+
To save testing time, the ``--parallel`` flag can be passed when running multiple environments at once.
207+
Some test groups are incompatible for parallel runs by nature of their configuration. Some labels have
208+
been added to the tox configuration for compatible tests to make running them easier.
209+
The following commands are thus recommended when you wish to take advantage of parallel runs.
210+
211+
.. dropdown:: Testing more than one group in parallel
212+
:animate: fade-in
213+
:icon: three-bars
214+
215+
.. list-table::
216+
:header-rows: 1
217+
:widths: auto
218+
219+
* - Command
220+
- Description
221+
* - python -m tox -m localparalleltests --parallel
222+
- Run all compatible test groups in parallel
223+
* - python -m tox -e othertests
224+
- Run incompatible test groups sequentially
225+
* - python -m pretest,test-api,test-launcher,posttest,kill-servers --parallel
226+
- Run specific selection of tests in parallel
227+
228+
Standalone DPF Server installation
229+
----------------------------------
230+
Standalone DPF Server is usually `installed in editable mode <https://dpf.docs.pyansys.com/version/dev/getting_started/dpf_server.html#install-dpf-server>`_.
231+
Accordingly, tox commands need to be adjusted for installation of standalone DPF Server in the isolated python environments
232+
tox creates to run these tests in. This is achieved by adding ``-x testenv.deps+="-e <path/to/dpf/standalone>"``
233+
to any of the previous tox commands.
234+
235+
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:
236+
237+
.. code-block:: bash
238+
239+
python -m tox -m localparalleltests --parallel -x testenv.deps+="-e ansys_dpf_server_lin_v2025.1.pre0"
240+
241+
.. warning::
242+
When the ANSYS_DPF_PATH environment variable is set, the server pointed to
243+
`takes precedence <https://dpf.docs.pyansys.com/version/dev/getting_started/dpf_server.html#manage-multiple-dpf-server-installations>`_
244+
over any other DPF Server installation method. Therefore, a standalone DPF Server installed in editable mode, in the
245+
presence of ANSYS_DPF_PATH environment variable, will be ignored.
246+
247+
With tox, a simple workaround is not setting this environment variable at the operating system level but passing it explicitly only when
248+
required. This is achived by adding ``-x testenv.setenv+="ANSYS_DPF_PATH=<path/to/valid/DPF/Server/installation>"`` to any tox command.
249+
250+
Alternatively, when set at the operating system level, commenting out the line where this environment variable is passed in the tox
251+
configuration file will ensure that it is ignored within the tox environments.
252+
253+
.. image:: tox.png
254+
255+
Testing on Linux via WSL
256+
------------------------
257+
Some system dependencies required for VTK to run properly might be missing when running tests on linux via WSL (or even linux in general).
258+
The identified workaround for this is to install the OSMesa wheel variant that leverages offscreen rendering with OSMesa.
259+
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
260+
achieved by adding ``-x testenv.commands_pre="uv pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==<version>"``
261+
262+
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:
263+
264+
.. code-block:: text
265+
266+
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"

0 commit comments

Comments
 (0)