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
.