[SciPy-Dev] Questions about docs

josef.pktd@gmai... josef.pktd@gmai...
Fri Apr 2 06:36:40 CDT 2010


On Fri, Apr 2, 2010 at 2:53 AM, David Goldsmith <d.l.goldsmith@gmail.com> wrote:
> 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.

my search only shows a brief discussion for module docstrings mainly for numpy

[SciPy-dev] "module docstrings"   September-October 2009

Josef

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


More information about the SciPy-Dev mailing list