[Doc-SIG] Python docs in reST

[Felix Wiemann]

Fred L. Drake, Jr. wrote:

> For most purposes, the standard include: directive seems good enough
> for me, so long as header-levels are all considered relative to
> context

I'm not sure what you mean.  Basically, the "include" *literally*
inserts the contents of the included file into the input stream.

> I've increasingly come to think that it makes sense to load all the
> documents as a single collection (one really big document), for the
> purposes of dealing with linking.

Yes.

If you want to load not only chapters but the *whole* Python
documentation into a document, you'd end up with unacceptable parse
times.  To fix this, you'd need to parse all input files (without
resolving references etc.) and store the results (namely Docutils node
trees) in XML files.  Later, when creating the big document, the XML
files can be read and assembled, which should probably not take very
much time.  Disadvantages:

* Need to use "make" or implement make-like functionality to regenerate
  XML files only when necessary.

* Need to be able to serialize Docutils node trees as XML.  There is
  currently an XML writer, but the original node tree isn't
  reconstructable from the XML files.  So we'd need to implement proper
  serialization support first (not too difficult, though).

> Splitting the output into separate pieces is a separate issue in many
> ways,

Yes.

> but needs to be done before other transformations.

What other transformations?

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/