[SciPy-Dev] Questions about docs
Fri Apr 2 06:36:40 CDT 2010
On Fri, Apr 2, 2010 at 2:53 AM, David Goldsmith <email@example.com> wrote:
> On Thu, Apr 1, 2010 at 11:17 PM, Warren Weckesser
> <firstname.lastname@example.org> 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.
my search only shows a brief discussion for module docstrings mainly for numpy
[SciPy-dev] "module docstrings" September-October 2009
>> > cheers
>> > David
>> > _______________________________________________
>> > SciPy-Dev mailing list
>> > SciPy-Dev@scipy.org
>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
>> SciPy-Dev mailing list
> Mathematician: noun, someone who disavows certainty when their uncertainty
> set is non-empty, even if that set has measure zero.
> SciPy-Dev mailing list
More information about the SciPy-Dev