[SciPy-dev] how scipy reference guide is generated

[josef.pktd at gmail.com]

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

Here is index.rst of scipy, the main part is that it specifies the
toctree, which refers to the individual sections rst files:

http://bazaar.launchpad.net/~scipystats/statsmodels/trunk/files/head%3A/scikits/statsmodels/docs/source/

Each individual.rst file then refers with the rst directives to the
actual source (.py module files), e.g.
http://docs.scipy.org/scipy/source/scipy/doc/source/interpolate.rst#1

the automodule, autosummary, autoclass, ... directives then direct
sphinx to which docstring from the source should be included in the
generated docs.

The tutorial here http://matplotlib.sourceforge.net/sampledoc/index.html
also looks useful, although I haven't read it, but it is referenced
from the the official docs of sphinx.

The numpy CodingStyleGuidelines are more about the formatting and
content of the docstrings, not really about the "getting started"
layout of sphinx generated docs

If you want to see a more verbose example, you can look at some of the
scikits, that's what I did when I set up this
http://bazaar.launchpad.net/~scipystats/statsmodels/trunk/files/head%3A/scikits/statsmodels/docs/source/

I hope that gets you a bit further.

Josef


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