[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Saturday 21 May 2005 20:03, Felix Wiemann wrote:
 > Yes.  It would be nice if Docutils were able to merge several input
 > documents into one, so that you could use internal links to link between
 > the parts (input files).

For most purposes, the standard include: directive seems good enough for me, 
so long as header-levels are all considered relative to context (probably 
already the case, but I haven't checked).

There may be a few cases where there may be benefit from being able to 
conditionalize content based on whether the document is standalone or not, 
but these seem unusual.  It may be that these could be better handled by 
having a component that is always subsidiary and using alternate containing 
documents.

 > A clean implementation would have to deal with multiple input files and
 > multiple output files as distinct and independent concepts, i.e. you
 > shouldn't need to have a 1:1 relation between input and output files.  I
 > don't have enough time (and interest) to develop such multi-file support
 > at the moment, though.  It may become important when we try to convert
 > the standard docs to reST, though.

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.  Splitting the output into separate pieces is a separate issue 
in many ways, but needs to be done before other transformations.  Which leads 
me to think it's just another transformation, and any transformation that 
runs after needs to be able to deal with multi-output structures.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>