Show More
@@ -31,7 +31,7 b' nicely spelled out in their guide. What follows is thus a lightly adapted' | |||
|
31 | 31 | version of the matplotlib documentation guide, taken with permission from the |
|
32 | 32 | MPL team. |
|
33 | 33 | |
|
34 |
.. __: http://matplotlib.sourceforge.net/d |
|
|
34 | .. __: http://matplotlib.sourceforge.net/devel/documenting_mpl.html | |
|
35 | 35 | |
|
36 | 36 | |
|
37 | 37 | A bit of Python code:: |
@@ -68,25 +68,36 b' A bit of shell code:' | |||
|
68 | 68 | echo "My home directory is: $HOME" |
|
69 | 69 | ls |
|
70 | 70 | |
|
71 | ||
|
72 | 71 | |
|
73 | 72 | Docstring format |
|
74 | 73 | ================ |
|
75 | 74 | |
|
76 | Good docstrings are very important. All new code will use `Epydoc`_ for | |
|
77 | generating API docs, so we will follow the `Epydoc`_ conventions. More | |
|
78 | specifically, we will use `reStructuredText`_ for markup and formatting, since | |
|
79 | it is understood by a wide variety of tools. This means that if in the future | |
|
80 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer | |
|
81 | transition pains. | |
|
75 | Good docstrings are very important. Unfortunately, Python itself only provides | |
|
76 | a rather loose standard for docstrings (`PEP 257`_), and there is no universally | |
|
77 | accepted convention for all the different parts of a complete docstring. | |
|
78 | However, the NumPy project has established a very reasonable standard, and has | |
|
79 | developed some tools to support the smooth inclusion of such docstrings in | |
|
80 | Sphinx-generated manuals. Rather than inventing yet another pseudo-standard, | |
|
81 | IPython will be henceforth documented using the NumPy conventions; we carry | |
|
82 | copies of some of the NumPy support tools to remain self-contained, but share | |
|
83 | back upstream with NumPy any improvements or fixes we may make to the tools. | |
|
84 | ||
|
85 | The `NumPy documentation guidelines`_ contain detailed information on this | |
|
86 | standard, and for a quick overview, the NumPy `example docstring`_ is a useful | |
|
87 | read. | |
|
88 | ||
|
89 | As in the past IPython used epydoc, currently many docstrings still use epydoc | |
|
90 | conventions. We will update them as we go, but all new code should be fully | |
|
91 | documented using the NumPy standard. | |
|
82 | 92 | |
|
83 | Details about using `reStructuredText`_ for docstrings can be found `here | |
|
84 | <http://epydoc.sourceforge.net/manual-othermarkup.html>`_. | |
|
93 | .. _PEP 257: http://www.python.org/peps/pep-0257.html | |
|
94 | .. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines | |
|
85 | 95 | |
|
86 | .. _Epydoc: http://epydoc.sourceforge.net/ | |
|
96 | .. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt | |
|
87 | 97 | |
|
88 |
Additional PEPs of interest regarding documentation of code |
|
|
98 | Additional PEPs of interest regarding documentation of code. While both of | |
|
99 | these were rejected, the ideas therein form much of the basis of docutils (the | |
|
100 | machinery to process reStructuredText): | |
|
89 | 101 | |
|
90 | - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ | |
|
91 | 102 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ |
|
92 | 103 | - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ |
General Comments 0
You need to be logged in to leave comments.
Login now