Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# Python
* [PEP8](https://pep8.org) applies.
* Functions methods that are not getters should start with a verb.
* [`flake8`](http://flake8.pycqa.org/en/latest/) with [`pep8-naming`](https://pypi.org/project/pep8-naming/)
should pass, with few exceptions.
Use the configuration file for
[pytools](https://gitlab.tiker.net/inducer/pytools/blob/master/setup.cfg)
as a guide.
When silencing warnings, be specific: `# noqa: F803` silences the specific
warning on that line.
Use an editor plugin to help with compliance.
* Consider using [pylint](https://pylint.org), especially for new code. It
finds many issues that `flake8` doesn't.
Use this [config file](https://gitlab.tiker.net/inducer/ci-support/blob/master/.pylintrc-default)
as a base.
* For Py3-only code, use type annotations.
* Think of compatibility/extensibility of functions. Specifically, document
which parameters are keyword-only. For Py3-only code, add the `*`
entry to explicitly denote that.
## Docstrings
* Processed using [sphinx](http://www.sphinx-doc.org/en/master/contents.html)
* Follows [ReStructuredText with sphinx conventions](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html)
(aka ReST).
* Start with some descriptive text, if needed--specifically if there
are concepts to explain.
* Use `:arg name:` and `:returns:` name to describe parameters and return values.
* Use `*name*` to refer to argument names.
* Enclose verbatim in-line source code in two backticks:
```rst
Use ``x-y`` to compute the difference.
```
* If a function is called `widget_as_json()`, don't feel the need to add a
docstring saying just "returns the widget as JSON."
* Be generous with ReST links, especially across projects. Add Intersphinx
URLs to `doc/conf.py` if needed.
* Use `.. autoclass/function/method` directives as shown below to generate
as much as possible of the documentation from docstrings.
Sample docstring:
```python
__doc__ = """
Widget-related functionality
.. autoclass:: Widget
.. autofunction:: widget_as_json
"""
class Widget(object):
.. attribute:: owner
A :class:`Widget` object or *None*.
.. automethod:: disown
"""
def disown(self, brutally=False):
"""
:arg brutally: if *True*, use violence.
"""
pass
def widget_as_json(widget, recursive=True):
"""Returns output compliant with the schema at :ref:`json-schema`.
Use ``widget[property]`` to access properties.
:arg widget: :class:`mymodule.Widget`
:returns: a :class:`dict` containing a JSON representation of *widget*.
.. versionadded:: 2018.1
.. versionchanged:: 2018.2
Added the *recursive* argument.
"""
```