[SciPy-Dev] Understanding source of docs, source file ".py" or ".rst" file

[Pauli Virtanen]

Tue, 29 Jun 2010 07:36:43 -0600, Vincent Davis wrote:
[clip]
> I guess my specific question is? When editing docs on the wiki should I
> edit, for example
> "scipy-docs/constants.rst"
> http://docs.scipy.org/scipy/docs/scipy-docs/constants.rst/#scipy-docs-
constants-rst
> or
> http://docs.scipy.org/scipy/docs/scipy.constants.constants/ or both
> or is it like Skipper said
> "I believe that you edit the .rst files via the docs wiki and that they
> are applied to the actual source modules by hand intermittently (ie.,
> before a release, when a lot of progress has been made, or after a docs
> marathon or sprint)."

The division of labor between module docstrings and the .rst files is not 
really resolved at the moment.

*Technically*, it would be possible to put everything to the module 
docstrings, and keep the .rst file as stubs. (The other way around is not 
technically feasible.) However, this is not what we're doing at the 
moment.

So at the moment, it's maybe best to concentrate on the .rst files since 
they are the most visible, and they're what ends up in the HTML docs.

-- 
Pauli Virtanen