[Doc-SIG] Getting started with restructured text

[David Goodger]

Hi Amos,

> I don't know much about restx, but what I've seen so far impresses me.
> The spec seems well thought out.

Thanks! We aim to please.

> * distutils doesn't add __init__.py files to the dps and parsers
> directories that it creates. This means that they aren't considered
> packages. I don't know if this is a distutils bug or a problem with how
> restx uses distutils.

That's odd. There *are* __init__.py files in those directories in CVS. I
just checked the latest CVS snapshot, and the files are there too. The
snapshots are generated daily but not archived (CVS is the archive); it's
possible that there may have been a glitch in the snapshot you downloaded.
Glitches been known to happen, but they've generally been all-or-nothing
(the SourceForge CVS repository is unavailable when the script is run,
etc.).

Perhaps it is a distutils thing? I can't say; I've been running code from my
local CVS tree. I'll make a point of periodically making sure
setup.py/install.py work correctly.

Those two files are just empty package indicators though. Others are not.

> * restx seems to require that the entire dps package be installed.

Yes. reStructuredText is a part of the DPS project. I felt it best to keep
them separate as I wanted to allow for alternate syntaxes (StructuredText
classic/NG, Setext, TeX, XML, or anything else anybody wanted to hack on).
DPS is currently little more than support for the reStructuredText parser
though.

I plan to merge the two projects at some point into the "docutils" project,
but I want to leave it until the ideas and APIs have matured. The parser is
nearly complete, but the rest of the system isn't there yet.

> * There is no obvious way to create HTML output. Should I write an HTML
> formatter along the lines shown in dps.formatters.model? Or is XSLT
> preferred?

That's up to you! Tony Ibbs has produced a first stab at what I call a
"Reader", a Python source analyzer, and an HTML "Writer", still available at
http://www.tibsnjoan.co.uk/reST/pydps.tgz. It's no longer being maintained
in favour of a fabled new implementation (which I'd love to see one of these
days). Several contributors have produced XSL stylesheets; they're available
in the reStructuredText "sandbox". Unfortunately, they're not up to date.

I plan to create a standalone Reader (i.e., input consists of standalone
reStructuredText source files without context), but haven't had time yet.

This is definitely a work in progress. Contributions would be most
appreciated!

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