##// END OF EJS Templates
[NumPyExampleDocstring] link was pointing to raw file
Bussonnier Matthias -
Show More
@@ -1,167 +1,167 b''
1 .. _documenting-ipython:
1 .. _documenting-ipython:
2
2
3 =====================
3 =====================
4 Documenting IPython
4 Documenting IPython
5 =====================
5 =====================
6
6
7 When contributing code to IPython, you should strive for clarity and
7 When contributing code to IPython, you should strive for clarity and
8 consistency, without falling prey to a style straitjacket. Basically,
8 consistency, without falling prey to a style straitjacket. Basically,
9 'document everything, try to be consistent, do what makes sense.'
9 'document everything, try to be consistent, do what makes sense.'
10
10
11 By and large we follow existing Python practices in major projects like Python
11 By and large we follow existing Python practices in major projects like Python
12 itself or NumPy, this document provides some additional detail for IPython.
12 itself or NumPy, this document provides some additional detail for IPython.
13
13
14
14
15 Standalone documentation
15 Standalone documentation
16 ========================
16 ========================
17
17
18 All standalone documentation should be written in plain text (``.txt``) files
18 All standalone documentation should be written in plain text (``.txt``) files
19 using reStructuredText [reStructuredText]_ for markup and formatting. All such
19 using reStructuredText [reStructuredText]_ for markup and formatting. All such
20 documentation should be placed in the directory :file:`docs/source` of the
20 documentation should be placed in the directory :file:`docs/source` of the
21 IPython source tree. Or, when appropriate, a suitably named subdirectory
21 IPython source tree. Or, when appropriate, a suitably named subdirectory
22 should be used. The documentation in this location will serve as the main
22 should be used. The documentation in this location will serve as the main
23 source for IPython documentation.
23 source for IPython documentation.
24
24
25 The actual HTML and PDF docs are built using the Sphinx [Sphinx]_
25 The actual HTML and PDF docs are built using the Sphinx [Sphinx]_
26 documentation generation tool. Once you have Sphinx installed, you can build
26 documentation generation tool. Once you have Sphinx installed, you can build
27 the html docs yourself by doing:
27 the html docs yourself by doing:
28
28
29 .. code-block:: bash
29 .. code-block:: bash
30
30
31 $ cd ipython-mybranch/docs
31 $ cd ipython-mybranch/docs
32 $ make html
32 $ make html
33
33
34 Our usage of Sphinx follows that of matplotlib [Matplotlib]_ closely. We are
34 Our usage of Sphinx follows that of matplotlib [Matplotlib]_ closely. We are
35 using a number of Sphinx tools and extensions written by the matplotlib team
35 using a number of Sphinx tools and extensions written by the matplotlib team
36 and will mostly follow their conventions, which are nicely spelled out in
36 and will mostly follow their conventions, which are nicely spelled out in
37 their documentation guide [MatplotlibDocGuide]_. What follows is thus a
37 their documentation guide [MatplotlibDocGuide]_. What follows is thus a
38 abridged version of the matplotlib documentation guide, taken with permission
38 abridged version of the matplotlib documentation guide, taken with permission
39 from the matplotlib team.
39 from the matplotlib team.
40
40
41 If you are reading this in a web browser, you can click on the "Show Source"
41 If you are reading this in a web browser, you can click on the "Show Source"
42 link to see the original reStricturedText for the following examples.
42 link to see the original reStricturedText for the following examples.
43
43
44 A bit of Python code::
44 A bit of Python code::
45
45
46 for i in range(10):
46 for i in range(10):
47 print i,
47 print i,
48 print "A big number:",2**34
48 print "A big number:",2**34
49
49
50 An interactive Python session::
50 An interactive Python session::
51
51
52 >>> from IPython.utils.path import get_ipython_dir
52 >>> from IPython.utils.path import get_ipython_dir
53 >>> get_ipython_dir()
53 >>> get_ipython_dir()
54 '/home/fperez/.config/ipython'
54 '/home/fperez/.config/ipython'
55
55
56 An IPython session:
56 An IPython session:
57
57
58 .. code-block:: ipython
58 .. code-block:: ipython
59
59
60 In [7]: import IPython
60 In [7]: import IPython
61
61
62 In [8]: print "This IPython is version:",IPython.__version__
62 In [8]: print "This IPython is version:",IPython.__version__
63 This IPython is version: 0.9.1
63 This IPython is version: 0.9.1
64
64
65 In [9]: 2+4
65 In [9]: 2+4
66 Out[9]: 6
66 Out[9]: 6
67
67
68
68
69 A bit of shell code:
69 A bit of shell code:
70
70
71 .. code-block:: bash
71 .. code-block:: bash
72
72
73 cd /tmp
73 cd /tmp
74 echo "My home directory is: $HOME"
74 echo "My home directory is: $HOME"
75 ls
75 ls
76
76
77 Docstring format
77 Docstring format
78 ================
78 ================
79
79
80 Good docstrings are very important. Unfortunately, Python itself only provides
80 Good docstrings are very important. Unfortunately, Python itself only provides
81 a rather loose standard for docstrings [PEP257]_, and there is no universally
81 a rather loose standard for docstrings [PEP257]_, and there is no universally
82 accepted convention for all the different parts of a complete docstring.
82 accepted convention for all the different parts of a complete docstring.
83 However, the NumPy project has established a very reasonable standard, and has
83 However, the NumPy project has established a very reasonable standard, and has
84 developed some tools to support the smooth inclusion of such docstrings in
84 developed some tools to support the smooth inclusion of such docstrings in
85 Sphinx-generated manuals. Rather than inventing yet another pseudo-standard,
85 Sphinx-generated manuals. Rather than inventing yet another pseudo-standard,
86 IPython will be henceforth documented using the NumPy conventions; we carry
86 IPython will be henceforth documented using the NumPy conventions; we carry
87 copies of some of the NumPy support tools to remain self-contained, but share
87 copies of some of the NumPy support tools to remain self-contained, but share
88 back upstream with NumPy any improvements or fixes we may make to the tools.
88 back upstream with NumPy any improvements or fixes we may make to the tools.
89
89
90 The NumPy documentation guidelines [NumPyDocGuide]_ contain detailed
90 The NumPy documentation guidelines [NumPyDocGuide]_ contain detailed
91 information on this standard, and for a quick overview, the NumPy example
91 information on this standard, and for a quick overview, the NumPy example
92 docstring [NumPyExampleDocstring]_ is a useful read.
92 docstring [NumPyExampleDocstring]_ is a useful read.
93
93
94
94
95 For user-facing APIs, we try to be fairly strict about following the above
95 For user-facing APIs, we try to be fairly strict about following the above
96 standards (even though they mean more verbose and detailed docstrings).
96 standards (even though they mean more verbose and detailed docstrings).
97 Wherever you can reasonably expect people to do introspection with::
97 Wherever you can reasonably expect people to do introspection with::
98
98
99 In [1]: some_function?
99 In [1]: some_function?
100
100
101 the docstring should follow the NumPy style and be fairly detailed.
101 the docstring should follow the NumPy style and be fairly detailed.
102
102
103 For purely internal methods that are only likely to be read by others extending
103 For purely internal methods that are only likely to be read by others extending
104 IPython itself we are a bit more relaxed, especially for small/short methods
104 IPython itself we are a bit more relaxed, especially for small/short methods
105 and functions whose intent is reasonably obvious. We still expect docstrings
105 and functions whose intent is reasonably obvious. We still expect docstrings
106 to be written, but they can be simpler. For very short functions with a
106 to be written, but they can be simpler. For very short functions with a
107 single-line docstring you can use something like::
107 single-line docstring you can use something like::
108
108
109 def add(a, b):
109 def add(a, b):
110 """The sum of two numbers.
110 """The sum of two numbers.
111 """
111 """
112 code
112 code
113
113
114 and for longer multiline strings::
114 and for longer multiline strings::
115
115
116 def add(a, b):
116 def add(a, b):
117 """The sum of two numbers.
117 """The sum of two numbers.
118
118
119 Here is the rest of the docs.
119 Here is the rest of the docs.
120 """
120 """
121 code
121 code
122
122
123
123
124 Here are two additional PEPs of interest regarding documentation of code.
124 Here are two additional PEPs of interest regarding documentation of code.
125 While both of these were rejected, the ideas therein form much of the basis of
125 While both of these were rejected, the ideas therein form much of the basis of
126 docutils (the machinery to process reStructuredText):
126 docutils (the machinery to process reStructuredText):
127
127
128 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
128 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
129 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
129 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
130
130
131 .. note::
131 .. note::
132
132
133 In the past IPython used epydoc so currently many docstrings still use
133 In the past IPython used epydoc so currently many docstrings still use
134 epydoc conventions. We will update them as we go, but all new code should
134 epydoc conventions. We will update them as we go, but all new code should
135 be documented using the NumPy standard.
135 be documented using the NumPy standard.
136
136
137 Building and uploading
137 Building and uploading
138 ======================
138 ======================
139 The built docs are stored in a separate repository. Through some github magic,
139 The built docs are stored in a separate repository. Through some github magic,
140 they're automatically exposed as a website. It works like this:
140 they're automatically exposed as a website. It works like this:
141
141
142 * You will need to have sphinx and latex installed. In Ubuntu, install
142 * You will need to have sphinx and latex installed. In Ubuntu, install
143 ``texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended``.
143 ``texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended``.
144 Install the latest version of sphinx from PyPI (``pip install sphinx``).
144 Install the latest version of sphinx from PyPI (``pip install sphinx``).
145 * Ensure that the development version of IPython is the first in your system
145 * Ensure that the development version of IPython is the first in your system
146 path. You can either use a virtualenv, or modify your PYTHONPATH.
146 path. You can either use a virtualenv, or modify your PYTHONPATH.
147 * Switch into the docs directory, and run ``make gh-pages``. This will build
147 * Switch into the docs directory, and run ``make gh-pages``. This will build
148 your updated docs as html and pdf, then automatically check out the latest
148 your updated docs as html and pdf, then automatically check out the latest
149 version of the docs repository, copy the built docs into it, and commit your
149 version of the docs repository, copy the built docs into it, and commit your
150 changes.
150 changes.
151 * Open the built docs in a web browser, and check that they're as expected.
151 * Open the built docs in a web browser, and check that they're as expected.
152 * (When building the docs for a new tagged release, you will have to add its link to
152 * (When building the docs for a new tagged release, you will have to add its link to
153 index.rst, then run ``python build_index.py`` to update index.html. Commit the
153 index.rst, then run ``python build_index.py`` to update index.html. Commit the
154 change.)
154 change.)
155 * Upload the docs with ``git push``. This only works if you have write access to
155 * Upload the docs with ``git push``. This only works if you have write access to
156 the docs repository.
156 the docs repository.
157 * If you are building a version that is not the current dev branch, nor a tagged release,
157 * If you are building a version that is not the current dev branch, nor a tagged release,
158 then you must run gh-pages.py directly with ``python gh-pages.py <version>``, and *not*
158 then you must run gh-pages.py directly with ``python gh-pages.py <version>``, and *not*
159 with ``make gh-pages``.
159 with ``make gh-pages``.
160
160
161 .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html
161 .. [reStructuredText] reStructuredText. http://docutils.sourceforge.net/rst.html
162 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
162 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
163 .. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html
163 .. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html
164 .. [PEP257] PEP 257. http://www.python.org/peps/pep-0257.html
164 .. [PEP257] PEP 257. http://www.python.org/peps/pep-0257.html
165 .. [NumPyDocGuide] NumPy documentation guide. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
165 .. [NumPyDocGuide] NumPy documentation guide. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
166 .. [NumPyExampleDocstring] NumPy example docstring. https://raw.github.com/numpy/numpy/master/doc/HOWTO_BUILD_DOCS.rst.txt
166 .. [NumPyExampleDocstring] NumPy example docstring. https://github.com/numpy/numpy/blob/master/doc/HOWTO_BUILD_DOCS.rst.txt
167
167
General Comments 0
You need to be logged in to leave comments. Login now