Contribute as a documentarian

Write documentation

Learn how to get started, use, and contribute to the project.

Write documentation

Add a new example

Write a new example to showcase the capabilities of PyAnsys Heart.

Write a new example

Build the documentation

Build the documentation to see your changes rendered.

Build the documentation

Write documentation

Sphinx is the tool used to generate PyAnsys Heart documentation. You write most of the content in ReStructuredText files. However, some of the content, like the examples, use a mix of ReStructuredText and Python files, thanks to Sphinx-Gallery. If you are interested in writing examples, see the Write a new example.

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

The layout of the doc/source directory is reflected in the URLs of the online documentation. For example, the doc/source/contribute/documentarian.rst file renders as the https://heart.health.docs.pyansys.com/version/stable/contribute/documentarian.html URL.

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

• Use lowercase letters for file and directory names.

• Use short and descriptive names.

• Use hyphens to separate words.

• Logically organize the hierarchy of the files and directories

You must include all files in the table of contents. Sphinx does not permit any orphan files. If you do not include a file in the table of contents, Sphinx raises a warning that causes the build to fail.

You declare the table of contents 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 a new example

The examples section of the documentation showcases different capabilities of PyAnsys Heart. Each example is a standalone Python script. You group related examples into subdirectories. Despite being PY files, they are written in a mix of ReStructuredText and Python. This is possible thanks to the Sphinx-Gallery extension.

Documentarians writing new examples are encouraged to familiarize themselves with Structuring Python scripts for Sphinx-Gallery. Once the PY file for a new example is properly set up, Sphinx-Gallery automatically generates Sphinx ReStructuredText (RST) files from it. The rendering of the resulting RST file for each example provides links for downloading a IPYNB (Jupyter notebook) and PY file.

Finally, here are some tips for writing examples:

• Start the example with an explanation of the main topic. Try to use as many relevant keywords as possible in this section for search engine optimization.

• Include an explanation with each code cell. The explanations should be included before, not after, the corresponding code.

• The examples are built with the documentation. During the build process, screenshots are inserted in the rendered document. You do not need to include the screenshots yourself.

• When creating a child directory that is to include multiple related examples, ensure that you include a README.txt file with the ReStructuredText content to use for the index page for this subsection’s examples in the generated documentation.

Build the documentation

Tox is used for automating the build of the documentation.

To install Tox:

python -m pip install tox

There are different environments for cleaning the build, building the documentation in different formats such as HTML and PDF, and running the tests.

The following environments are available:

Documentation environments

Environment	Description	Command
doc-links	Environment for verifying the integrity of external links within the documentation	python -m tox -e doc-links
doc-html	Environment for generating HTML documentation	python -m tox -e doc-html
doc-pdf	Environment for generating PDF documentation	python -m tox -e doc-pdf
doc-clean	Environment for cleaning documentation generated files	python -m tox -e doc-clean