[SciPy-dev] how scipy reference guide is generated

[josef.pktd at gmail.com]

On Wed, Dec 23, 2009 at 10:04 PM, Forrest Sheng Bao
<forrest.bao at gmail.com> wrote:
> 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:

I don't know what your layout is, but the index file in doc/source
should be a pure rst file not a python script. The python module files
should be accessible through the python path. For some of the numpy
specific rst directives and formatting you need the numpy sphinx
plugins, but I don't remember if section headers in doc strings belong
to that group.

The best way to get started is to look or copy some existing examples,
pick any package that uses sphinx. Alternatively, I saw recently a
package on pypi that creates your package structure including the
sphinx doc layout, but unfortunately I don't remember the name and I
didn't look at it.

Josef


> 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
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>