[Doc-SIG] Re: "docutils"

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> Who knows... If we're successful, we might even subsume pydoc! At
> least, pydoc could be made to utilize the DPS to process its
> docstrings.

I was carefully not thinking/saying that! Also, pydoc is a much "lighter
weight" solution (at least as it stood last time I looked), and thus is
valuable for that alone (by "lighter weight" I simply mean that it
doesn't have as many dependencies, it's much smaller/more
self-contained).

> > * overall package "docutils"
> > * subpackage "docutils.dps"
> > * subpackage "docutils.rest" or "docutils.rst"
>
> You're after a flatter package structure. That loses some context
> information though; 'dps.parsers.restructuredtext',
> 'dps.modes.pysource', and 'dps.formatters.html' are obviously
> different things. We don't really need the namespace space provided
> by nested packages; it would be easy enough to avoid duplicate names.

Hmm - I *meant* to be advocating simply taking what is now "dps" and
renaming it to "docutils.dps", and similarly for "restructuredtext" -
which to my mind gives us a *deeper* package structure (albeit by one
level!).

So one would refer to "docutils.dps.parsers.rest" (for instance) if one
is only doing minimal change (well, the external user might not - but
that's why we have __init__.py files).

(I'd assumed a Grand Plan for the current package structures, so didn't
want to contemplate changing them!)

Extra parsers (and I agree it's good to keep that door open, even if we
never use it) could then either slot into docutils directly - so we
might (!) have "docutils.pod" - or would be entirely separate and
require "conscious" registration.

> Definitely time for a new SourceForge project!

Oh, I can tell you're enjoying this!

> At least we can reserve the name and have it point to DPS
> & reStructuredText.

Yes, I think that's sensible.

> Once we have more of the pieces in place it will be easier to
> decide how to arrange them.

Yes - I wasn't expecting instant answers to the suggestion...

> > (pyreport? pyinfo? pyman? pysillywalk?)
>
> I like 'pysource'.

OK - let's tentatively go for that. I *may* hold off on renaming what
I'm working on for the moment, though, until it's a bit mature (not that
I've worked on it this week, ho hum).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)