[SciPy-Dev] Questions about docs

[Warren Weckesser]

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.

Warren


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