[SciPy-Dev] More doc Marathon prioritization

[Scott Sinclair]

>On 22 June 2010 20:35, David Goldsmith <d.l.goldsmith@gmail.com> wrote:
> On Tue, Jun 22, 2010 at 10:17 AM, Warren Weckesser
> <warren.weckesser@enthought.com> wrote:
>>
>> David Goldsmith wrote:
>> > On Tue, Jun 22, 2010 at 6:59 AM, Scott Sinclair <scott.sinclair.za
>> > <http://scott.sinclair.za>@gmail.com <http://gmail.com>> wrote:
>> >
>> >     >On 22 June 2010 14:33, Warren Weckesser
>> >     <warren.weckesser@enthought.com
>> >     <mailto:warren.weckesser@enthought.com>> wrote:
>> >     > I asked about "package/info.py" and "doc/source/package.rst"
>> >     back in April:
>> >     >
>> >     >
>> >  http://mail.scipy.org/pipermail/scipy-dev/2010-April/014065.html
>> >     >
>> >     > My conclusion at that time was that both had to be maintained,
>> >     despite
>> >     > the apparent duplication.
>> >
>> >     Perhaps it's best to focus documentation improvements on
>> >     "doc/source/package.rst" until this issue can be resolved. The
>> > result
>> >     of processing "doc/source/package.rst" is what currently ends up at
>> >     http://docs.scipy.org and "faces the world".
>> >
>> >     As far as I can see, it looks like the contents of "package/info.py"
>> >     will need to be maintained by hand. Unless Sphinx processing becomes
>> >     part of the regular build process? However, I doubt  that
>> > complicating
>> >     the build would be worth avoiding the maintenance effort.
>> >
>> >     In any case, I don't think the content in "package/info.py" and
>> >     "doc/source/package.rst" needs to contain an excessive amount of
>> >     explanation and narrative - that surely belongs in
>> >     "doc/source/tutorial/package.rst"?
>> >
>> > Sorry, guys, I'm lost: I can't find either of those - complete
>> > URLs/path-names, please.
>> >
>>
>> Sorry, I was using "package" as a placeholder for any scipy module.  For
>> example, if "package" is "linalg", there is module-level documentation
>> in both scipy/linalg/info.py and in doc/source/linalg.rst (both relative
>> to subversion trunk).
>
> OK, thanks.  (FWIW, perhaps this is old-skool, but I've often seen - and
> used - <package>/info.py as a formalism for that kind of thing.)

As a concrete example, if <package> == interpolate

<package>/info.py is what you edit at
http://docs.scipy.org/scipy/docs/scipy.interpolate/

doc/source/<package>.rst is what you edit at
http://docs.scipy.org/scipy/docs/scipy-docs/interpolate.rst/

doc/source/tutorial/<package>.rst is what you edit at
http://docs.scipy.org/scipy/docs/scipy-docs/tutorial/interpolate.rst/

Cheers,
Scott