@@ -8,7 +8,7 @@ numpydoc docstring guide
8
8
.. Contents ::
9
9
10
10
This document describes the syntax and best practices for docstrings used with
11
- the numpydoc extension for ` Sphinx < http://sphinx-doc.org/ >`__ .
11
+ the numpydoc extension for Sphinx _ .
12
12
13
13
.. Note ::
14
14
@@ -21,21 +21,23 @@ the numpydoc extension for `Sphinx <http://sphinx-doc.org/>`__.
21
21
Overview
22
22
--------
23
23
We mostly follow the standard Python style conventions as described here:
24
- * `Style Guide for C Code <http ://python.org/dev/peps/pep-0007/ >`_
25
- * `Style Guide for Python Code <http ://python.org/dev/peps/pep-0008/ >`_
26
- * `Docstring Conventions <http ://python.org/dev/peps/pep-0257/ >`_
24
+ * `Style Guide for C Code <https ://www. python.org/dev/peps/pep-0007/ >`_
25
+ * `Style Guide for Python Code <https ://www. python.org/dev/peps/pep-0008/ >`_
26
+ * `Docstring Conventions <https ://www. python.org/dev/peps/pep-0257/ >`_
27
27
28
28
Additional PEPs of interest regarding documentation of code:
29
- * `Docstring Processing Framework <http ://python.org/dev/peps/pep-0256/ >`_
30
- * `Docutils Design Specification <http ://python.org/dev/peps/pep-0258/ >`_
29
+ * `Docstring Processing Framework <https ://www. python.org/dev/peps/pep-0256/ >`_
30
+ * `Docutils Design Specification <https ://www. python.org/dev/peps/pep-0258/ >`_
31
31
32
32
Use a code checker:
33
- * `pylint <http://www.logilab.org/857 >`_
34
- * `pyflakes <https://pypi.python.org/pypi/pyflakes >`_
35
- * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py >`_
36
- * `flake8 <https://pypi.python.org/pypi/flake8 >`_
37
- * `vim-flake8 <https://github.com/nvie/vim-flake8 >`_ plugin for
38
- automatically checking syntax and style with flake8
33
+ * pylint _: a Python static code analysis tool.
34
+ * pyflakes _: a tool to check Python code for errors by parsing
35
+ the source file instead of importing it.
36
+ * pycodestyle _: (formerly ``pep8 ``) a tool to check Python code against
37
+ some of the style conventions in PEP 8.
38
+ * flake8 _: a tool that glues together ``pycodestyle ``, ``pyflakes ``,
39
+ ``mccabe `` to check the style and quality of Python code.
40
+ * vim-flake8 _: a ``flake8 `` plugin for Vim.
39
41
40
42
Import conventions
41
43
------------------
@@ -332,7 +334,7 @@ The sections of a function's docstring are:
332
334
An optional section that provides additional information about the
333
335
code, possibly including a discussion of the algorithm. This
334
336
section may include mathematical equations, written in
335
- `LaTeX <http ://www.latex-project.org/ >`_ format::
337
+ `LaTeX <https ://www.latex-project.org/ >`_ format::
336
338
337
339
The FFT is a fast implementation of the discrete Fourier transform:
338
340
@@ -686,6 +688,11 @@ Conclusion
686
688
This document itself was written in ReStructuredText.
687
689
:ref: `An example <example >` of the format shown here is available.
688
690
689
- .. _SciPy : http://www.scipy.org
690
- .. _numpy-discussion list : http://scipy.org/scipylib/mailing-lists.html
691
- .. _Sphinx : http://sphinx.pocoo.org
691
+ .. _Sphinx : https://www.sphinx-doc.org/
692
+ .. _pylint : https://pypi.org/project/pylint/
693
+ .. _pyflakes : https://pypi.python.org/pypi/pyflakes/
694
+ .. _pycodestyle : https://pypi.org/project/pycodestyle/
695
+ .. _flake8 : https://pypi.python.org/pypi/flake8/
696
+ .. _vim-flake8 : https://github.com/nvie/vim-flake8
697
+ .. _SciPy : https://www.scipy.org
698
+ .. _numpy-discussion list : https://scipy.org/scipylib/mailing-lists.html
0 commit comments