##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Small doc updates.
Fernando Perez -
Show More
Show file before | Show file after | Hide comments
@@ -1,76 +1,92 b''
1 .. _documenting-ipython:
2
3 =====================
1 Documenting IPython
4 Documenting IPython
2 ===================
5 =====================
3
6
4 Standalone documentation
7 Standalone documentation
5 ------------------------
8 ========================
6
9
7 All standalone documentation should be written in plain text (``.txt``) files
10 All standalone documentation should be written in plain text (``.txt``) files
8 using `reStructuredText`_ for markup and formatting. All such documentation
11 using `reStructuredText`_ for markup and formatting. All such documentation
9 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
10 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
11 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
12 documentation and all existing documentation should be converted to this
15 documentation and all existing documentation should be converted to this
13 format.
16 format.
14
17
15 In the future, the text files in the ``docs`` directory will be used to
18 The actual HTML and PDF docs are built using the Sphinx_ documentation
16 generate all forms of documentation for IPython. This include documentation on
19 generation tool. Sphinx has been adopted as the default documentation tool for
17 the IPython website as well as *pdf* documentation.
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.
18
22
19 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
23 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
24 .. _Sphinx: http://sphinx.pocoo.org/
20
25
21 A bit of shell code:
22
26
23 .. code-block:: bash
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
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
31 version of the matplotlib documentation guide, taken with permission from the
32 MPL team.
24
33
25 cd /tmp
34 .. __: http://matplotlib.sourceforge.net/doc/html/devel/documenting_mpl.html
26 echo "My home directory is: $HOME"
27 ls
28
35
29 A bit of Python code:
30
36
31 .. code-block:: python
37 A bit of Python code::
32
38
33 for i in range(10):
39 for i in range(10):
34 print i,
40 print i,
35 print "A big number:",2**34
41 print "A big number:",2**34
36
42
37 An interactive Python session:
43 An interactive Python session::
38
39 .. code-block:: python
40
44
41 >>> from IPython import genutils
45 >>> from IPython import genutils
42 >>> genutils.get_ipython_dir()
46 >>> genutils.get_ipython_dir()
43 '/home/fperez/.ipython'
47 '/home/fperez/.ipython'
44
48
45
49
46 An IPython session:
50 An IPython session:
47
51
48 .. code-block:: ipython
52 .. code-block:: ipython
49
53
50 In [8]: import IPython
54 In [7]: import IPython
51
55
52 In [9]: print "This IPython is version:",IPython.__version__
56 In [8]: print "This IPython is version:",IPython.__version__
53 This IPython is version: 0.9.1
57 This IPython is version: 0.9.1
54
58
59 In [9]: 2+4
60 Out[9]: 6
61
62
63 A bit of shell code:
64
65 .. code-block:: bash
66
67 cd /tmp
68 echo "My home directory is: $HOME"
69 ls
70
55
71
56
72
57 Docstring format
73 Docstring format
58 ----------------
74 ================
59
75
60 Good docstrings are very important. All new code will use `Epydoc`_ for
76 Good docstrings are very important. All new code will use `Epydoc`_ for
61 generating API docs, so we will follow the `Epydoc`_ conventions. More
77 generating API docs, so we will follow the `Epydoc`_ conventions. More
62 specifically, we will use `reStructuredText`_ for markup and formatting, since
78 specifically, we will use `reStructuredText`_ for markup and formatting, since
63 it is understood by a wide variety of tools. This means that if in the future
79 it is understood by a wide variety of tools. This means that if in the future
64 we have any reason to change from `Epydoc`_ to something else, we'll have fewer
80 we have any reason to change from `Epydoc`_ to something else, we'll have fewer
65 transition pains.
81 transition pains.
66
82
67 Details about using `reStructuredText`_ for docstrings can be found `here
83 Details about using `reStructuredText`_ for docstrings can be found `here
68 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
84 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
69
85
70 .. _Epydoc: http://epydoc.sourceforge.net/
86 .. _Epydoc: http://epydoc.sourceforge.net/
71
87
72 Additional PEPs of interest regarding documentation of code:
88 Additional PEPs of interest regarding documentation of code:
73
89
74 - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
90 - `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
75 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
91 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
76 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
92 - `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