Contributing to the documentation#

Note

Overall guidance on contributing to the documentation of a PyAnsys repository appears in Documenting in the PyAnsys Developer’s Guide.

You must also follow the Documentation style guide to ensure that all the documentation looks the same across the project.

To contribute on the documentation you must start by setting up the PyDPF-Core repository by following the steps in Contributing as a developer section.

In this page you can check how to :

Structure the documentation

How the documentation is structured and where to locate files.

Structure the documentation

Write documentation

Explains and showcases the use of PyDPF-Core.

Write documentation

Build the documentation

Render the documentation to see your changes reflected.

Build the documentation

Structure the documentation#

The documentation generator used in PyDPF-Core is Sphinx. Most of the documents are written in reStructuredText.

The documentation is located in the doc/source directory. The landing page is declared in the doc/source/index.rst file. The rest of the files contain the main pages of different sections of the documentation. Finally, the doc/source/_static/ folder contains various assets like images, and CSS files.

The layout of the doc/source directory is reflected in the slug of the online documentation. For example, the doc/source/getting_started/contribute/documentarian.rst renders as https://dpf.docs.pyansys.com/getting_started/contribute/documentarian.html.

Thus, if you create a new file, it important to follow these rules:

Use lowercase letters for file and directory names
Use short and descriptive names
Play smart with the hierarchy of the files and directories

All files need to be included in a table of contents. No dangling files are permitted. If a file is not included in the table of contents, Sphinx raises a warning.

A table of contents can be declared using a directive like this:

.. toctree::
    :hidden:
    :maxdepth: 3

    path-to-file-A
    path-to-file-B
    path-to-file-C
    ...

The path to the file is relative to the directory where the table of contents is declared.

Write documentation#

Our documentation tries to follow a structure principle that respects four different functions of the documentation. Each of them fulfills a different need for people working with our tool at different times, in different circumstances.

Here is an overview of how our documentation is organized to help you know where you should include your contributions. Each section has their own guidelines that must be followed when creating new content. To check these specific guidelines click on the correspondent card below.

Learning oriented

TUTORIALS

Function: Teach how to get started and use PYDPF-core step by step

Teach how to perform a task and showcase the underlying concepts, providing detailed explanations at each stage. A tutorial is centered around a given feature.

Writing tutorials

Use-cases oriented

EXAMPLES

Function: Show how to solve specifics key problems

Showcase a specific key problem or use-case with a complete PyDPF script. They are more advanced than tutorials as they present end-to-end engineering workflows and assume basic knowledge of PyDPF-Core.

Writing examples

Understanding oriented

CONCEPTS

Function: Provide useful theoretical explanations for PyDPF-Core

Discuss and explain key DPF principles and concepts, for the reader to understand the spirit of the underlying tool.

Informing oriented

API REFERENCE

Function: Describe PyDPF-Core APIs

Provides technical reference on how PyDPF-Core works and how to use it but assume basic understanding of key DPF concepts. It is generated automatically along the documentation and is based on the source code.

Build the documentation#

Tox is used for automating the build of the documentation. To install Tox, run

python -m pip install tox tox-uv

There are different tox environments for cleaning previous build, building the HTML documentation, and checking the integrity of external links. The following environments are available:

Documentation environments

Environment	Description	Command
doc-clean	Environment for cleaning previously generated html documentation	python -m tox -e doc-clean
doc-links	Environment for verifying the integrity of external links within the documentation	python -m tox -e doc-links
doc-html	Environment for html documentation generation	python -m tox -e doc-html

Two environment variables are available for the documentation build:

BUILD_EXAMPLES: if set to true, the examples are built. This is the default behavior. When set to false, the examples are not built.
BUILD_API: if set to true, the API documentation is built. This is the default behavior. When set to false, the API documentation is not built.

By using these environment variables, you can speed up the build process. This allows to shorten the build time when only certain parts of the documentation are modified.

Tip

Instead of setting environment variables at the operating system level, you can add -x testenv:<env_name>.setenv+="<env_var>=<env_var_value>" to the previous tox commands. This can also be repeated to set multiple environment variables through tox. For example, to build HTML documentation while excluding both examples and API during the build, you can use the following command:

python -m tox -e doc-html -x testenv:doc-html.setenv+="BUILD_API=false" -x testenv:doc-html.setenv+="BUILD_EXAMPLES=false"