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

[Scott Sinclair]

On 29 June 2010 15:36, Vincent Davis <vincent at vincentdavis.net> wrote:
> On Tue, Jun 29, 2010 at 2:55 AM, Pauli Virtanen <pav at iki.fi> wrote:
>> Mon, 28 Jun 2010 23:04:39 -0500, Skipper Seabold wrote:
>> [clip]
>>> I also struggled to understand this at first.  Is this documented
>>> somewhere?  If not, where would be best?  I'm thinking somewhere on the
>>> main docs page.  I don't know that the Question and Answers page is
>>> obvious enough.  Would the "before you start" be a good place?
>>
>> If you think about how Sphinx works, all this becomes clear. But perhaps
>> it should be explicitly explained somewhere.
>>
> 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/
> or
> http://docs.scipy.org/scipy/docs/scipy.constants.constants/

It's most helpful if you edit the above, for now.

> 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)."

It's the other way around. The file doc/source/constants.rst [1] is
processed by Sphinx during the documentation build process to produce
some of the content in the SciPy reference guide at
http://docs.scipy.org/. The documentation in the source file
scipy/constants/constants.py [2] can eventually be pulled into the
reference guide using the appropriate Sphinx directives in
constants.rst.

Cheers,
Scott

[1] edited via the doc wiki at
http://docs.scipy.org/scipy/docs/scipy-docs/constants.rst/
[2] edited via the doc wiki at
http://docs.scipy.org/scipy/docs/scipy.constants.constants/