[SciPy-Dev] More doc Marathon prioritization

David Goldsmith d.l.goldsmith@gmail....
Wed Jun 23 03:06:15 CDT 2010


On Wed, Jun 23, 2010 at 12:20 AM, Scott Sinclair <scott.sinclair.za@
gmail.com> wrote:

> >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
>

Thanks, Scott.

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100623/5d3370cb/attachment.html 


More information about the SciPy-Dev mailing list