[SciPy-dev] how scipy reference guide is generated

[Forrest Sheng Bao]

Hi Josef,

Thanks for your answer. I am kinda confused and lost. I am a little bit
anxious that I can go thru the process converting a Python script to an HTML
file.

Maybe I didn't formulate my questions clearly at the beginning. I want to
generate HTML or LaTeX docs from comments in my Python files, where my
comments are in reST format.

I saw that code in the doc page of scipy is like the format of my code. The
page
http://docs.scipy.org/scipy/source/scipy/dist/lib64/python2.4/site-packages/scipy/linalg/decomp.pycontains
comments in reST format. I assume that I can generate an HTML page
from Python code with comments and my comments will automatically become the
contents of the HTML page. that's why I specify such a file as my master
file when run sphinx-quickstart, though it seems that I am wrong.

I have been reading this guide line all night without a clue.
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines

At the end of that page, there is an example, example.py, which is a python
code commented by reST docstrings. But I couldn't find any documents telling
me what to do to that file.

There is another example at the end of that page, HOWTO_BUILD_DOCS.txt which
is in reST syntax. I can convert it using rst2html command, but fail to use
Sphinx to generate HTML as itself explained. I did "easy_install numpydoc"
and set "extensions = ['numpydoc']" in conf.py. But when I tried to "make
html," I saw this:

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v0.6.3

Extension error:
Unknown event name: autodoc-process-docstring
make: *** [html] Error 1


Maybe that numpydoc has bugs?

On Wed, Dec 23, 2009 at 9:47 PM, <josef.pktd at gmail.com> wrote:

> 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.
>

I couldn't find a doc telling me what that rst file should contain and how
my python modules will be included in such an rst file.

I feel that Sphinx can not process any Python file but only reST file.

But how can I convert a Python script into reST file?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091223/7a79e03f/attachment.html>