[Doc-SIG] Re: "docutils"

[David Goodger]

[David]
> How about "dps.modes.pythondocstring" or just "dps.modes.docstring"

[Paul]
> One point - while I'm in favour of descriptive names, I'd avoid
> making them too long.

The end-user will never see these names, of course.

> I'd prefer dps.parsers.rest (or rst, I'll keep out of that fight...)

No fight, just a discussion with a certain amound of hyperbole and
emphasis thrown in for good measure. We're all quite civil here!
I usually read a message, mull it over for a while, and reread it
before drafting my reply. That tends to stop emotions from clouding
the issues.

> But it's possibly too late for that.

Not too late. Better now than once it's in the standard library.
("In my mind, I use the power of positive visualization...")

[Tony]
> But that doesn't address what to call the command line tool

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.

> and it also doesn't take account of the fact that it's handling much
> more than the docstrings...

How about 'pysource' for the 'extracting from Python source code and
manipulating into useful documentation' mode?

> although it *might* be that the 'suck in a Python package/module and
> report on it' stuff should actually be a different module than
> docutils (was DPS) itself.

A middleman module between compiler.py and DPS would be just fine by
me. But there's still the DPS end of the 'Python source code' mode to
be considered.

[Tony]
> Could I respectfully suggest a radical restructuring, sooner rather
> than later (since at the moment we have the number of users under
> close control!):
> 
> * 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.

The advantage of nested packages is that they might obviate the need
for registering modules/subpackages. The 'languages' subpackage of
restructuredtext allows the import of a language module using a string
argument, like 'en'. There is no lookup table; just drop the code in
place and go. But if we flatten out the structure and ask for a 'WXYZ'
formatter, either it has to be registered or we run the risk of
importing the wrong type of code.

Definitely time for a new SourceForge project! At least we can reserve
the name and have it point to DPS & reStructuredText. Eventually,
reStructuredText will be subsumed into DPS (or distutils) anyway. Once
we have more of the pieces in place it will be easier to decide how to
arrange them.

> This *may* answer the question of where to put the "Python source
> code" parsing stuff later on - it would naturally go into (for
> instance) "docutils.py<some-mnemonic>" (pyreport? pyinfo? pyman?
> pysillywalk?)

I like 'pysource'.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net