Skip to content

Commit 1258994

Browse files
committed
Move numpydoc validation to doc formatting tools
1 parent 2c964f1 commit 1258994

File tree

3 files changed

+39
-15
lines changed

3 files changed

+39
-15
lines changed

doc/source/doc-style/docstrings.rst

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,8 @@
1-
Numpydoc docstrings
1+
Numpydoc Docstrings
22
###################
33

44
When writing docstrings for PyAnsys libraries, use the `numpydoc`_
5-
style, regardless as to whether you are using this Sphinx extension or the
6-
`napoleon <https://pypi.org/project/sphinxcontrib-napoleon/>`_ Sphinx extension
7-
to generate your library documentation.
8-
9-
You add the extension to use for documentation generation in your ``conf.py`` file.
10-
For example, to use `numpydoc`_, you would add:
11-
12-
.. code:: python
13-
14-
extensions = [
15-
'numpydoc',
16-
...
17-
]
5+
style.
186

197
For consistency within PyAnsys libraries, always use ``"""`` to introduce and conclude a
208
docstring, keeping the line length shorter than 70 characters. Ensure that there are

doc/source/doc-style/formatting-tools.rst

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,41 @@ Alternate tools to `interrogate`_ are `docstr-coverage`_ and
7272
output resembling that of `pytest-cov`_, which is the the equivalent tool
7373
for source code coverage.
7474

75+
Numpydoc Validation
76+
-------------------
77+
In order to validate the style of :ref:`Numpydoc Docstrings`, it is possible to
78+
take advantage of `numpydoc`_ Sphinx extension. Note that this extension will
79+
only check for those objcts whose docstring needs to be rendered. It is not a
80+
command line tool which checks all docstrings style in your source code.
81+
82+
Because it is a Sphinx extension, it needs to be configured via through the
83+
``conf.py``. see :ref:`The \`\`doc/\`\` directory`. Start by adding it to the
84+
list of extensions:
85+
86+
.. code-block:: python
87+
88+
extensions = [
89+
'numpydoc',
90+
...
91+
]
92+
93+
Once added, you can select which `validation checks
94+
<https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_
95+
need to be addressed by using the ``numpydoc_validation_checks`` dictionary:
96+
97+
.. code-block:: python
98+
99+
numpydoc_validation_checks = {"GL08"}
100+
101+
This will issue the following warning for any object without a docstring:
102+
103+
.. code-block:: python
104+
105+
"The object does not have a docstring"
106+
107+
For a complete list of available checks, please check the `full mapping of
108+
validation checks
109+
<https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_.
75110

76111
Pydocstyle
77112
----------
@@ -98,3 +133,4 @@ under the ``[tool.pydocstyle]`` entry:
98133
.. _docformatter: https://github.com/PyCQA/docformatter
99134
.. _codespell: https://github.com/codespell-project/codespell
100135
.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
136+
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html

doc/source/doc-style/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The documentation for a PyAnsys library should contain:
3131
Finally, the documentation should be public and hosted via gh-pages, either as
3232
a branch named ``gh-pages`` within the library repository or within a
3333
``gh-pages`` branch within ``<library-repository>-docs``. For more information,
34-
see :ref:`documentation_deployment`.
34+
see :ref:`Continuous Documentation Deployment`.
3535

3636
.. toctree::
3737
:hidden:

0 commit comments

Comments
 (0)