Re: [Docutils-develop] subdocs branch

[Guenter M. <mi...@us...>]

Dear Berend, dear Docutils developers,

On 2011-01-13, Berend van Berkum wrote:

...

> I've been digging around the docutils codebase of and on for a couple
> of years now, and been member of the Du lists for almost one year. 
> Right now I'm asking myself if and what there is to be contributed to
> the project itself. I have plenty of ideas myself.

> Subdocs, lossless rst and nested-inline I all find desirable improvements on 
> the current publisher. 

Of these three, I would give an rst writer priority. There are also
patches for nested-inline on the Docutils tracker which would need
review and adaption to the current state of the trunk.

> Also, and this may be out of the scope of Du/rSt, I have been thinking and 
> experimenting with a non-standalone, host-based publisher that would index 
> various nodes in a DB. I do think this could help large aggregated documents 
> and other voluminous document bases such as websites. But for a real 
> improvement there'd probably be a need for some caching and a review of the 
> include mechanism. I noticed Du merges docs, while in a hypertext context I 
> wonder if a <include /> node would not be an option (HTML can include client-
> side using frames or <html:object />)

> Anyway, perhaps this'll move the focus too much towards a build-system 
> and there are ways around the long publisher runs such as builing individual
> files only.
> Just some thoughts.

For projects (as opposed to single documents), Sphinx
(http://sphinx.pocoo.org/) is the "state of the art". It is tested on
large projects (including the official Python documentation), in active
development, and includes many of the tools desirable for larger bodies
of documentation (indexing, cross linking, breadcrumbs, sidebar toc, ...)
as well as a more capable (and complex) configuration scheme. 

One of my priorities is to get Sphinx and Docutils closer together again,
so that "dual use" of rst source documents becomes more easy. Besides
cross-porting features that are relevant for the other part, I envisage a
"compatibility" mode/include-file that would provide dummy/fallback roles
and directives for Sphinx additions.

Günter