Show More
@@ -1,92 +1,103 b'' | |||||
1 | .. _documenting-ipython: |
|
1 | .. _documenting-ipython: | |
2 |
|
2 | |||
3 | ===================== |
|
3 | ===================== | |
4 | Documenting IPython |
|
4 | Documenting IPython | |
5 | ===================== |
|
5 | ===================== | |
6 |
|
6 | |||
7 | Standalone documentation |
|
7 | Standalone documentation | |
8 | ======================== |
|
8 | ======================== | |
9 |
|
9 | |||
10 | All standalone documentation should be written in plain text (``.txt``) files |
|
10 | All standalone documentation should be written in plain text (``.txt``) files | |
11 | using `reStructuredText`_ for markup and formatting. All such documentation |
|
11 | using `reStructuredText`_ for markup and formatting. All such documentation | |
12 | should be placed in the top level directory ``docs`` of the IPython source |
|
12 | should be placed in the top level directory ``docs`` of the IPython source | |
13 | tree. Or, when appropriate, a suitably named subdirectory should be used. The |
|
13 | tree. Or, when appropriate, a suitably named subdirectory should be used. The | |
14 | documentation in this location will serve as the main source for IPython |
|
14 | documentation in this location will serve as the main source for IPython | |
15 | documentation and all existing documentation should be converted to this |
|
15 | documentation and all existing documentation should be converted to this | |
16 | format. |
|
16 | format. | |
17 |
|
17 | |||
18 | The actual HTML and PDF docs are built using the Sphinx_ documentation |
|
18 | The actual HTML and PDF docs are built using the Sphinx_ documentation | |
19 | generation tool. Sphinx has been adopted as the default documentation tool for |
|
19 | generation tool. Sphinx has been adopted as the default documentation tool for | |
20 | Python itself as of version 2.6, as well as by a number of projects that |
|
20 | Python itself as of version 2.6, as well as by a number of projects that | |
21 | IPython is related with, such as numpy, scipy, matplotlib, sage and nipy. |
|
21 | IPython is related with, such as numpy, scipy, matplotlib, sage and nipy. | |
22 |
|
22 | |||
23 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html |
|
23 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
24 | .. _Sphinx: http://sphinx.pocoo.org/ |
|
24 | .. _Sphinx: http://sphinx.pocoo.org/ | |
25 |
|
25 | |||
26 |
|
26 | |||
27 | The rest of this document is mostly taken from the `matploblib |
|
27 | The rest of this document is mostly taken from the `matploblib | |
28 | documentation`__; we are using a number of Sphinx tools and extensions written |
|
28 | documentation`__; we are using a number of Sphinx tools and extensions written | |
29 | by the matplotlib team and will mostly follow their conventions, which are |
|
29 | by the matplotlib team and will mostly follow their conventions, which are | |
30 | nicely spelled out in their guide. What follows is thus a lightly adapted |
|
30 | nicely spelled out in their guide. What follows is thus a lightly adapted | |
31 | version of the matplotlib documentation guide, taken with permission from the |
|
31 | version of the matplotlib documentation guide, taken with permission from the | |
32 | MPL team. |
|
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 | A bit of Python code:: |
|
37 | A bit of Python code:: | |
38 |
|
38 | |||
39 | for i in range(10): |
|
39 | for i in range(10): | |
40 | print i, |
|
40 | print i, | |
41 | print "A big number:",2**34 |
|
41 | print "A big number:",2**34 | |
42 |
|
42 | |||
43 | An interactive Python session:: |
|
43 | An interactive Python session:: | |
44 |
|
44 | |||
45 | >>> from IPython import genutils |
|
45 | >>> from IPython import genutils | |
46 | >>> genutils.get_ipython_dir() |
|
46 | >>> genutils.get_ipython_dir() | |
47 | '/home/fperez/.ipython' |
|
47 | '/home/fperez/.ipython' | |
48 |
|
48 | |||
49 |
|
49 | |||
50 | An IPython session: |
|
50 | An IPython session: | |
51 |
|
51 | |||
52 | .. code-block:: ipython |
|
52 | .. code-block:: ipython | |
53 |
|
53 | |||
54 | In [7]: import IPython |
|
54 | In [7]: import IPython | |
55 |
|
55 | |||
56 | In [8]: print "This IPython is version:",IPython.__version__ |
|
56 | In [8]: print "This IPython is version:",IPython.__version__ | |
57 | This IPython is version: 0.9.1 |
|
57 | This IPython is version: 0.9.1 | |
58 |
|
58 | |||
59 | In [9]: 2+4 |
|
59 | In [9]: 2+4 | |
60 | Out[9]: 6 |
|
60 | Out[9]: 6 | |
61 |
|
61 | |||
62 |
|
62 | |||
63 | A bit of shell code: |
|
63 | A bit of shell code: | |
64 |
|
64 | |||
65 | .. code-block:: bash |
|
65 | .. code-block:: bash | |
66 |
|
66 | |||
67 | cd /tmp |
|
67 | cd /tmp | |
68 | echo "My home directory is: $HOME" |
|
68 | echo "My home directory is: $HOME" | |
69 | ls |
|
69 | ls | |
70 |
|
70 | |||
71 |
|
||||
72 |
|
71 | |||
73 | Docstring format |
|
72 | Docstring format | |
74 | ================ |
|
73 | ================ | |
75 |
|
74 | |||
76 | Good docstrings are very important. All new code will use `Epydoc`_ for |
|
75 | Good docstrings are very important. Unfortunately, Python itself only provides | |
77 | generating API docs, so we will follow the `Epydoc`_ conventions. More |
|
76 | a rather loose standard for docstrings (`PEP 257`_), and there is no universally | |
78 | specifically, we will use `reStructuredText`_ for markup and formatting, since |
|
77 | accepted convention for all the different parts of a complete docstring. | |
79 | it is understood by a wide variety of tools. This means that if in the future |
|
78 | However, the NumPy project has established a very reasonable standard, and has | |
80 | we have any reason to change from `Epydoc`_ to something else, we'll have fewer |
|
79 | developed some tools to support the smooth inclusion of such docstrings in | |
81 | transition pains. |
|
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 |
|
93 | .. _PEP 257: http://www.python.org/peps/pep-0257.html | |
84 | <http://epydoc.sourceforge.net/manual-othermarkup.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 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ |
|
102 | - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_ | |
92 | - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ |
|
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