[SciPy-dev] how scipy reference guide is generated

[Forrest Sheng Bao]

I am getting quite struggling now. I commented my Python code with reST but
i counldn't generate expected HTML file. I expect that I can combine both my
code and comments together in one doc and use Sphinx to only get the code
out.

I have a very simple file, index.py, containing only one dummy function:

dd(a, b):
"""The sum of two numbers.
 Parameters
----------
 a: an integer
b: an integer

Returns
 -------
a + b, the sum of a and b.
"""
 return a+b

I set up a project under current directory using sphinx-quickstart. And
then, I run "make hitml"

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v0.6.3
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: [config changed] 3 added, 0 changed, 0 removed
reading sources... [ 66%] index
reST markup error:
/forrest/work/BME/NKdata/Features/sphinx/index.py:5: (SEVERE/4) Unexpected
section title.

Parameters
----------
make: *** [html] Error 1

I do not understand why. Why it is unexpected? And, even if I delete the
---------, the triple quotes bracing my comments in Python file never
disappear in final doc.

Cheers,
Forrest
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091223/9f735ad1/attachment.html>