blob: fd058d9bd3de7649637371053de4b6a52825901c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
=========================================
Building the NumPy API and reference docs
=========================================
Using Sphinx_
-------------
`Download <https://code.launchpad.net/~stefanv/scipy/numpy-refguide>`_
the builder. Follow the instructions in ``README.txt``.
Using Epydoc_
-------------
Currently, we recommend that you build epydoc from the trunk::
svn co https://epydoc.svn.sf.net/svnroot/epydoc/trunk/epydoc epydoc
cd epydoc/src
sudo python setup.py install
The appearance of some elements can be changed in the epydoc.css
style sheet.
Emphasized text appearance can be controlled by the definition of the <em>
tag. For instance, to make them bold, insert::
em {font-weight: bold;}
The variables' types are in a span of class rst-classifier, hence can be
changed by inserting something like::
span.rst-classifier {font-weight: normal;}
The first line of the signature should **not** copy the signature unless
the function is written in C, in which case it is mandatory. If the function
signature is generic (uses ``*args`` or ``**kwds``), then a function signature
may be included.
Use optional in the "type" field for parameters that are non-keyword
optional for C-functions.
Epydoc depends on Docutils for reStructuredText parsing. You can
download Docutils from the `Docutils sourceforge
page. <http://docutils.sourceforge.net/>`_. The version in SVN is
broken, so use 0.4 or the patched version from Debian. You may also
be able to use a package manager like yum to install it::
$ sudo yum install python-docutils
Example
-------
Here is a short example module,
`plain text <http://svn.scipy.org/svn/numpy/trunk/doc/example.py>`_
or
`rendered <http://www.scipy.org/doc/example>`_ in HTML.
To try this yourself, simply download the example.py::
svn co http://svn.scipy.org/svn/numpy/trunk/doc/example.py .
Then, run epydoc::
$ epydoc --docformat=restructuredtext example.py
The output is placed in ``./html``, and may be viewed by loading the
``index.html`` file into your browser.
.. _epydoc: http://epydoc.sourceforge.net/
.. _sphinx: http://sphinx.pocoo.org
|
