1
- .. _docstrings :
2
-
3
- Docstring Standards
1
+ Numpydoc Docstrings
4
2
###################
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
14
3
15
- extensions = [' numpydoc' ,
16
- # other extensions
17
- ]
4
+ When writing docstrings for PyAnsys libraries, use the `numpydoc `_
5
+ style.
18
6
19
7
For consistency within PyAnsys libraries, always use ``""" `` to introduce and conclude a
20
8
docstring, keeping the line length shorter than 70 characters. Ensure that there are
@@ -39,11 +27,12 @@ classes, methods, and variables. For example::
39
27
style.
40
28
41
29
42
- Minimum Section Requirements
43
- ----------------------------
30
+ Required Docstring Sections
31
+ ===========================
32
+
44
33
PyAnsys library docstrings contain these `numpydoc `_ sections as a minimum:
45
34
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 >`_
47
36
* `Extended Summary <https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary >`_ if applicable
48
37
* `Parameters <https://numpydoc.readthedocs.io/en/latest/format.html#parameters >`_ if applicable
49
38
* `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:
52
41
These sections should follow numpydoc style. To avoid inconsistencies between
53
42
PyAnsys libraries, adhere to the additional style guidelines that follow.
54
43
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
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
64
A class is a 'noun' representing a collection of methods. For consistency within PyAnsys libraries,
58
65
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 ::
60
67
61
68
class FieldAnalysis3D(Analysis):
62
69
"""Manages 3D field analysis setup in HFSS, Maxwell 3D, and Q3D.
@@ -67,19 +74,20 @@ summary if applicable::
67
74
...
68
75
"""
69
76
70
-
71
77
Ensure that there is a line break between the end of a class docstring and the subsequent methods.
72
78
73
- Methods
74
- ~~~~~~~
79
+ Short Summaries for Methods
80
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
81
A method is a 'verb' representing an action that can be performed. For consistency within PyAnsys
76
82
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 ::
78
84
79
85
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
+ """
81
90
82
-
83
91
Methods with a leading underscore (_) are 'protected' methods, meaning that they are not rendered in the
84
92
documentation unless an explicit request is made to add them using Sphinx directives. However, clearly
85
93
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
91
99
just the GET method. Examples should be included to demonstrate usage.
92
100
93
101
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:
97
108
98
- Here is an example of a 'Parameters' section for a class in PyAEDT::
109
+ .. code-block :: rst
99
110
100
111
Parameters
101
112
----------
@@ -144,83 +155,116 @@ parameter, the description specifies the default along with any information that
144
155
be needed about the behavior that occurs when the default is used.
145
156
146
157
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
150
163
151
164
Returns
152
165
-------
153
- dict
166
+ dict
154
167
Dictionary of components with their absolute paths.
155
168
156
169
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
159
174
160
175
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
163
188
``True`` when successful, ``False`` when failed.
164
189
190
+ It is possible for more than one item to be returned:
165
191
166
- It is possible for more than one item to be returned::
192
+ .. code-block :: rst
167
193
168
194
Returns
169
- --------
170
- type
195
+ -------
196
+ type
171
197
Ground object.
172
- str
198
+ str
173
199
Ground name.
174
200
175
-
176
201
If a method does not have a decorator, the basic implementation of Python
177
202
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.
179
204
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
+ --------
185
207
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:
187
213
188
- To include the docstring of a function within Sphinx, you use the
189
- ``autofunction:: `` directive:
214
+ .. code-block :: rst
190
215
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.
192
220
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...
194
225
195
- This directive renders the sample function as:
196
226
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.
204
229
205
- numpydoc_validation_checks = {"GL08"}
206
230
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:
208
236
209
- "The object does not have a docstring"
237
+ - ``.. note:: `` directive is useful for highlighting important
238
+ information once the documentation gets rendered.
210
239
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.
215
242
243
+ - ``.. deprecated:: X.Y.Z `` to inform the user about the deprecated status of
244
+ the object or functionality.
216
245
217
- Additional Information
218
- ----------------------
219
246
You can find additional information and examples at `numpydoc `_. Reference
220
247
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
224
268
225
269
.. _numpydoc : https://numpydoc.readthedocs.io/en/latest/format.html
226
270
.. _googledoc : https://google.github.io/styleguide/
0 commit comments