[SciPy-Dev] Questions about docs

David Goldsmith d.l.goldsmith@gmail....
Fri Apr 2 01:53:29 CDT 2010


On Thu, Apr 1, 2010 at 11:17 PM, Warren Weckesser <
warren.weckesser@enthought.com> wrote:

> David Cournapeau wrote:
> > Warren Weckesser wrote:
> >
> >> Each package has the file "info.py" (e.g. scipy/linalg/info.py) that
> >> contains a docstring.  For linalg, roughly the same information is in
> >> doc/source/linalg.rst.  Which is the file that is currently maintained,
> >> and which can we get rid of?  Running "make html" in doc/ uses the .rst
> >> file, but the corresponding web page at docs.scipy.org
> >> (http://docs.scipy.org/scipy/docs/scipy.linalg/) appears to be from the
> >> file info.py.
> >>
> >> More basic question:  when I have the trunk checked out, what is "the
> >> way" to build the docs?
> >>
> >
> > If you want to build the doc for the scipy you have in your trunk, you
> > need to build and install scipy first (so that the docstrings can be
> > extracted).
> >
> > The way I do it when generating the scipy binaries is:
> >       - create a virtual env and activate it
> >       - install scipy through python setupsconsegg.py install (or
> setupegg.py
> > - I prefer using scons because I can build scipy very quickly on a
> > multicore machine)
> >       - then build the doc (cd doc && make html)
> >
> >
>
>
> Thanks.  I've just been doing "python setup.py build", and then setting
> PYTHONPATH to the "lib..." subdirectory of build/ when I want to switch
> to the trunk version of scipy.
>
> So, the HTML documentation for, say, linalg, comes from
> doc/source/linalg.rst, but the actual docstring associated with
> scipy.linalg comes from info.py.  The format of the two files is
> different--the .rst file uses a lot more sphinx automation goodness--so
> I guess they both have to be maintained.  But it sure would be nice if,
> say, the .rst file could be generated from the docstring in info.py.
>

This rings a bell vis-a-vis the previous conclusion; I'll check to see if
anyone opened a ticket asking for such an enhancement.

DG


>
> Warren
>
> > cheers
> >
> > David
> > _______________________________________________
> > SciPy-Dev mailing list
> > SciPy-Dev@scipy.org
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>



-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100401/27676f6f/attachment.html 


More information about the SciPy-Dev mailing list