Documentation style tools

There are plenty of tools for documentation style and coverage. This section presents some of the most popular ones in the Python ecosystem. A minimum configuration is provided for each one so you can easily include them in your PyAnsys project.

Most of the tools presented can be configured using The pyproject.toml file, avoiding dotfiles and thus leading to a much cleaner root project directory.

Blacken-Docs

When writing documentation, it is frequent to include code-blocks which are used as examples. However, these code snippets style cannot be verified with the usual code formatting tools. This is where blacken-docs comes into play. You can execute this tool by running:

blacken-docs -l <line-length> doc/**/*.rst

Codespell

Codespell checks for common misspellings in text files. This implies that it is not limited to Python files but can run checks on any human-readable file.

It is possible to ignore words that are flagged as misspelled. You can specify these words in a file that can then be passed to Codespell by running:

codespell --write-changes --ignore-words=<FILE>

Docformatter

Docformatter automatically formats Python docstrings according to PEP 257. To make sure Docformatter wraps your docstrings at a given number of characters, use the following configuration:

docformatter -r -i --wrap-summaries <length> --wrap-descriptions <length> src

Doctest

Doctest is a module from the Python standard library, which means it is included by default with your Python installation. It is used for checking the examples provided inside docstrings to make sure that they reflect the current usage of the source code. Doctest can be integrated with pytest in The pyproject.toml file:

[tool.pytest.ini_options]
addopts = "--doctest-modules"

Interrogate

Interrogate is a tool for checking docstring coverage. Similar to source code coverage tools, this tool tests how many functions, classes, and modules in a Python library hold a docstring.

[tool.interrogate]
exclude = ["setup.py", "doc", "tests"]
color = true
verbose = 2

Alternate tools to interrogate are docstr-coverage and docstring-coverage. However, interrogate is modern and maintained, with output resembling that of pytest-cov, which is the equivalent tool for source code coverage.

Numpydoc validation

To validate the style of Numpydoc docstrings, you can take advantage of the numpydoc Sphinx extension. Note that this extension checks only for those objects whose docstrings must be rendered. It is not a command line tool that checks the style of all docstrings in your source code.

Because numpydoc is a Sphinx extension, it must be configured in the conf.py file. See The doc/ directory. Start by adding it to the list of extensions:

extensions = ["numpydoc", ...]

Once the numpydoc extension is added, you can select which validation checks must be addressed by using the numpydoc_validation_checks dictionary:

numpydoc_validation_checks = {"GL08"}

This issues the following warning for any object without a docstring:

"The object does not have a docstring"

For a complete list of available checks, see the full mapping of validation checks.

Pydocstyle

Pydocstyle is a tool for checking the compliance of Python docstrings with PEP 257. Its configuration can be defined in the The pyproject.toml file. By default, Pydocstyle matches all *.py files except those starting with test_*.py. The default configuration should be enough for a PyAnsys project. However, if additional configuration is needed, it must be included it under the [tool.pydocstyle] entry:

[tool.pydocstyle]
convention = "numpy"

Vale

Vale is a tool for maintaining a consistent style and voice in your documentation. Its configuration is defined in a .vale.ini file in the library’s doc folder. For PyAnsys libraries, Vale is configured to apply the guidelines in the Google developer documentation style guide, along with any custom Ansys rules and terminology lists, to reStructuredText (RST) and Markdown (MD) files.

After a PyAnsys team member implements Vale in your PyAnsys library, you can check any content changes that you make in supported files locally.

In the library’s doc folder, download the package with:

vale sync

Check all files in the doc folder with:

vale .

Check all files in the repository, by going to the root directory and running:

vale --config=doc/.vale.ini .

Check all files in only a particular folder with vale followed by the name of the folder.

Address any warnings and issues that display by either editing the file to fix or adding a term to the accept.txt file under the doc folder in styles\Vocab\ANSYS.