[SciPy-Dev] More doc Marathon prioritization

[David Goldsmith]

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"?
> >
> >     Cheers,
> >     Scott
> >
> >
> > 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).
>
> Warren
>

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

DG

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



-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100622/3b985aac/attachment.html