Skip to content

Commit e5d3c62

Browse files
jorgepilotoPipKatMaxJPRey
authored
ENH: new doc style guide (#85)
* Move documentation_style/ -> doc-style/ * Update API Documentation Style -> Documentation Style * Fix pydocstyle configuration * Reformat docstrings.rst file * Remove duplicated section about doc deployment * Move numpydoc validation to doc formatting tools * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Remove 'how to class documentation' from doc style * Improve docstrings layout * Add doc generation in how to * Update doc/source/doc-style/docstrings.rst Co-authored-by: Maxime Rey <[email protected]> * Add blacken-docs to formatting-tools * Apply code suggestions * Clarify parameters section Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: Maxime Rey <[email protected]>
1 parent 0df8489 commit e5d3c62

File tree

12 files changed

+291
-214
lines changed

12 files changed

+291
-214
lines changed

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,4 @@ doc/build/
1818
venv/
1919

2020
# sphinx autogen
21-
doc/source/documentation_style/api/*
21+
doc/source/guidelines/api/*

doc/source/coding_style/pep8_best_practices.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -444,7 +444,7 @@ docstring style, which is used by `numpy <https://numpy.org/>`_,
444444
`scipy <https://www.scipy.org/>`_, `pandas
445445
<https://pandas.pydata.org/>`_, and a variety of other Python open
446446
source projects. For more information on docstrings for PyAnsys
447-
libraries, see :ref:`api_documentation`.
447+
libraries, see :ref:`Documentation Style`.
448448

449449

450450
Programming Recommendations
Lines changed: 119 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,8 @@
1-
.. _docstrings:
2-
3-
Docstring Standards
1+
Numpydoc Docstrings
42
###################
5-
When writing docstrings for PyAnsys libraries, use the `numpydoc`_
6-
style, regardless as to whether you are using this Sphinx extension or the
7-
`napoleon <https://pypi.org/project/sphinxcontrib-napoleon/>`_ Sphinx extension
8-
to generate your library documentation.
9-
10-
You add the extension to use for documentation generation in your ``conf.py`` file.
11-
For example, to use `numpydoc`_, you would add:
12-
13-
.. code:: python
143

15-
extensions = ['numpydoc',
16-
# other extensions
17-
]
4+
When writing docstrings for PyAnsys libraries, use the `numpydoc`_
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
@@ -39,11 +27,12 @@ classes, methods, and variables. For example::
3927
style.
4028

4129

42-
Minimum Section Requirements
43-
----------------------------
30+
Required Docstring Sections
31+
===========================
32+
4433
PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
4534

46-
* `Short description <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_
35+
* `Short Summary <https://numpydoc.readthedocs.io/en/latest/format.html#short-summary>`_
4736
* `Extended Summary <https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary>`_ if applicable
4837
* `Parameters <https://numpydoc.readthedocs.io/en/latest/format.html#parameters>`_ if applicable
4938
* `Returns <https://numpydoc.readthedocs.io/en/latest/format.html#returns>`_ if applicable
@@ -52,11 +41,29 @@ PyAnsys library docstrings contain these `numpydoc`_ sections as a minimum:
5241
These sections should follow numpydoc style. To avoid inconsistencies between
5342
PyAnsys libraries, adhere to the additional style guidelines that follow.
5443

55-
Classes
56-
~~~~~~~
44+
45+
Short Summary
46+
-------------
47+
This is a single line that goes immediately after the declaration of the class
48+
or function to briefly describe what the class or function does. The
49+
`short summary` is mandatory. If it is not present, :ref:`Doc Style Tools` will
50+
raise an error.
51+
52+
The short summary can be declared on the same line as the opening quotes or on
53+
the next line. While `PEP 257
54+
<https://peps.python.org/pep-0257>`_ accepts both ways, you must be consistent across your
55+
project. If you decide to declare the short summary on the same line,
56+
refer to :ref:`Numpydoc Validation` because the ``"GL01"`` check must be
57+
disabled.
58+
59+
The guidelines for documenting short summaries differ for classes versus
60+
functions.
61+
62+
Short Summaries for Classes
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
5764
A class is a 'noun' representing a collection of methods. For consistency within PyAnsys libraries,
5865
always start the brief description for a class with a verb ending in 's', followed by an extended
59-
summary if applicable::
66+
summary in a new line if additional information is needed::
6067

6168
class FieldAnalysis3D(Analysis):
6269
"""Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D.
@@ -67,19 +74,20 @@ summary if applicable::
6774
...
6875
"""
6976

70-
7177
Ensure that there is a line break between the end of a class docstring and the subsequent methods.
7278

73-
Methods
74-
~~~~~~~
79+
Short Summaries for Methods
80+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
7581
A method is a 'verb' representing an action that can be performed. For consistency within PyAnsys
7682
libraries, always start the brief description for a method with a verb not ending in 's', followed
77-
by an extended summary if applicable::
83+
by an extended summary in a new line if additional information is needed::
7884

7985
def export_mesh_stats(self, setup_name, variation_string="", mesh_path=None):
80-
"""Export mesh statistics to a file."""
86+
"""Export mesh statistics to a file.
87+
88+
...
89+
"""
8190
82-
8391
Methods with a leading underscore (_) are 'protected' methods, meaning that they are not rendered in the
8492
documentation unless an explicit request is made to add them using Sphinx directives. However, clearly
8593
written descriptions for private methods are still important.
@@ -91,11 +99,14 @@ add a docstring for the setter. A setter simply exposes both the GET and SET met
9199
just the GET method. Examples should be included to demonstrate usage.
92100

93101
Parameters
94-
~~~~~~~~~~
95-
Both classes and methods have parameters in their function signatures. All parameters in a function
96-
signature should appear in the 'Parameters' section for the class or method.
102+
----------
103+
Functions and class methods may have parameters in their signatures. All these
104+
parameters should be documented in the ``Parameters`` section.
105+
signature should appear in the ``Parameters`` section for the class or method.
106+
107+
Here is an example of a ``Parameters`` section for a class in PyAEDT:
97108

98-
Here is an example of a 'Parameters' section for a class in PyAEDT::
109+
.. code-block:: rst
99110
100111
Parameters
101112
----------
@@ -144,83 +155,116 @@ parameter, the description specifies the default along with any information that
144155
be needed about the behavior that occurs when the default is used.
145156

146157
Returns
147-
~~~~~~~
148-
The 'Returns' section contains only the return data type and a brief description
149-
that concludes with a period::
158+
-------
159+
The ``Returns`` section contains only the return data type and a brief description
160+
that concludes with a period:
161+
162+
.. code-block:: rst
150163
151164
Returns
152165
-------
153-
dict
166+
dict
154167
Dictionary of components with their absolute paths.
155168
156169
157-
A class does not have a 'Returns' section. If a Boolean is returned, format the
158-
'Returns` section like this::
170+
A class does not have a ``Returns`` section. If a ``Boolean`` is returned, format the
171+
``Returns`` section like this:
172+
173+
.. code-block:: rst
159174
160175
Returns
161-
--------
162-
bool
176+
-------
177+
bool
178+
``True`` when successful, ``False`` when failed.
179+
180+
It is possible for the ``Returns`` section to look like the ``Parameters`` section
181+
if variable names are provided:
182+
183+
.. code-block:: rst
184+
185+
Returns
186+
-------
187+
has_succeeded : bool
163188
``True`` when successful, ``False`` when failed.
164189
190+
It is possible for more than one item to be returned:
165191

166-
It is possible for more than one item to be returned::
192+
.. code-block:: rst
167193
168194
Returns
169-
--------
170-
type
195+
-------
196+
type
171197
Ground object.
172-
str
198+
str
173199
Ground name.
174200
175-
176201
If a method does not have a decorator, the basic implementation of Python
177202
methods is used. In this case, while ``None`` is returned, you do not document it.
178-
Consequently, such a method does not have a 'Returns' section.
203+
Consequently, such a method does not have a ``Returns`` section.
179204

180-
Example Docstrings
181-
------------------
182-
Methods and functions should generally be documented within the
183-
'Examples' section to make the usage of the method or function clear.
184-
Here is a sample function:
205+
Examples
206+
--------
185207

186-
.. literalinclude:: sample_func.py
208+
The ``Examples`` section provides a quick reference on how to use a method or
209+
a function. This section must be compliant with the `doctest
210+
<https://docs.python.org/3/library/doctest.html>`_ format and is not supposed to
211+
replace your test suite but complement it. As an example,
212+
consider the following function:
187213

188-
To include the docstring of a function within Sphinx, you use the
189-
``autofunction::`` directive:
214+
.. code-block:: rst
190215
191-
.. code::
216+
Examples
217+
--------
218+
Create an instance of HFSS and connect to an existing HFSS
219+
design or create a new HFSS design if one does not exist.
192220
193-
.. autofunction:: pyansys_sphinx_theme.sample_func.func
221+
>>> from pyaedt import Hfss
222+
>>> hfss = Hfss()
223+
pyaedt info: No project is defined...
224+
pyaedt info: Active design is set to...
194225
195-
This directive renders the sample function as:
196226
197-
.. autofunction:: pyansys_sphinx_theme.sample_func.func
198-
199-
200-
Validation
201-
----------
202-
Enable validation of docstrings during the Sphinx build by adding the
203-
following line to the ``conf.py`` file::
227+
If the definition of the function is updated, this
228+
section must be updated too.
204229

205-
numpydoc_validation_checks = {"GL08"}
206230

207-
This will issue the following warning for any object without a docstring::
231+
Additional Directives
232+
=====================
233+
Since Python docstrings are written using RST syntax, it is possible to take
234+
advantage of some directives available in this Markup language. Among those, it
235+
is possible to find:
208236

209-
"The object does not have a docstring"
237+
- ``.. note::`` directive is useful for highlighting important
238+
information once the documentation gets rendered.
210239

211-
The ``"GL08"`` code is required at minimum for PyAnsys libraries.
212-
Other codes may be enforced at a later date. For a full listing,
213-
see `Validation <https://numpydoc.readthedocs.io/en/latest/validation.html#validation>`_
214-
in the `numpydoc`_.
240+
- ``.. warning::`` is usually used to point out an action that might result in
241+
data loss.
215242

243+
- ``.. deprecated:: X.Y.Z`` to inform the user about the deprecated status of
244+
the object or functionality.
216245

217-
Additional Information
218-
----------------------
219246
You can find additional information and examples at `numpydoc`_. Reference
220247
this documentation as the primary source regarding docstring styles for directives
221-
that are not covered here. For example, you use the ``note::`` directive to highlight
222-
important information and the ``warning::`` directive to point out an action that
223-
might result in data loss.
248+
that are not covered here.
249+
250+
251+
Example
252+
=======
253+
254+
A generic docstring example compliant with PyAnsys guidelines is shown below:
255+
256+
.. literalinclude:: code/sample_func.py
257+
258+
To include the docstring of a function within Sphinx, you use the
259+
``autofunction::`` directive:
260+
261+
.. code::
262+
263+
.. autofunction:: pyansys_sphinx_theme.sample_func.func
264+
265+
This directive renders the sample function as:
266+
267+
.. autofunction:: pyansys_sphinx_theme.sample_func.func
224268

225269
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
226270
.. _googledoc: https://google.github.io/styleguide/

doc/source/documentation_style/formatting-tools.rst renamed to doc/source/doc-style/formatting-tools.rst

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
1-
Formatting Tools
2-
================
3-
1+
Doc Style Tools
2+
===============
43
There are plenty of tools for documentation style and coverage. This section
54
presents some of the most popular ones in the Python ecosystem. A minimum
65
configuration is provided for each one so you can easily include them in your
@@ -11,6 +10,19 @@ Most of the tools presented can be configured using :ref:`the
1110
cleaner root project directory.
1211

1312

13+
Blacken-Docs
14+
------------
15+
16+
When writing documentation, it is frequent to include code-blocks which are used
17+
as examples. However, these code snippets style cannot be verified with the usual code
18+
formatting tools. This is where `blacken-docs`_ comes into play. You can execute
19+
this tool by running:
20+
21+
.. code:: bash
22+
23+
blacken-docs -l <line-length> doc/**/*.rst
24+
25+
1426
Codespell
1527
---------
1628

@@ -72,6 +84,41 @@ Alternate tools to `interrogate`_ are `docstr-coverage`_ and
7284
output resembling that of `pytest-cov`_, which is the the equivalent tool
7385
for source code coverage.
7486

87+
Numpydoc Validation
88+
-------------------
89+
To validate the style of :ref:`Numpydoc Docstrings`, it is possible to
90+
take advantage of the `numpydoc`_ Sphinx extension. Note that this extension
91+
checks only for those objects whose docstrings must be rendered. It is not a
92+
command line tool that checks the style of all docstrings in your source code.
93+
94+
Because `numpydoc`_ is a Sphinx extension, it must be configured in the
95+
``conf.py`` file. See :ref:`The \`\`doc/\`\` directory`. Start by adding it to the
96+
list of extensions:
97+
98+
.. code-block:: python
99+
100+
extensions = [
101+
'numpydoc',
102+
...
103+
]
104+
105+
Once the `numpydoc`_ extension is added, you can select which `validation checks
106+
<https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_
107+
must be addressed by using the ``numpydoc_validation_checks`` dictionary:
108+
109+
.. code-block:: python
110+
111+
numpydoc_validation_checks = {"GL08"}
112+
113+
This will issue the following warning for any object without a docstring:
114+
115+
.. code-block:: python
116+
117+
"The object does not have a docstring"
118+
119+
For a complete list of available checks, see the `full mapping of
120+
validation checks
121+
<https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks>`_.
75122

76123
Pydocstyle
77124
----------
@@ -86,9 +133,10 @@ under the ``[tool.pydocstyle]`` entry:
86133
.. code:: toml
87134
88135
[tool.pydocstyle]
89-
# Additional configuration
136+
convention = "numpy"
90137
91138
139+
.. _blacken-docs: https://github.com/asottile/blacken-docs
92140
.. _interrogate: https://interrogate.readthedocs.io/en/latest/
93141
.. _docstr-coverage: https://docstr-coverage.readthedocs.io/en/latest/index.html
94142
.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage/wiki/Home
@@ -98,3 +146,4 @@ under the ``[tool.pydocstyle]`` entry:
98146
.. _docformatter: https://github.com/PyCQA/docformatter
99147
.. _codespell: https://github.com/codespell-project/codespell
100148
.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
149+
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html

0 commit comments

Comments
 (0)