[TYPO3-doc] Tatata Ta: The TYPO3 Sphinx Theme

[Xavier Perseguers]

Hi,

> I would suggest to keep the manuscript pages in one folder though.
> Then we could import all pages with a
>
>     egovapi/*
>
> like I did in the example. I would say proceed like Xavier did:
>
> ./myextension/index.rst
> ./myextension/chapter1.rst
> ./myextension/chapter2.rst
> ./myextension/images/...

To do it the right way, we should have a master document including any 
subdocument. The problem is that AFAIK reading the reST documentation, 
this implies using some "raw" reST commands which should definitely be 
disabled on any online system (which I did in my online converter).

So I'd say that we should either forbid this entirely (single document 
manual.rst like we currently have manual.sxw, period) or have a real 
good filtering engine that makes sure raw inclusion of external 
subdocuments is OK but absolutely nothing else.

> Probably the names of the documents should sort alphabetically to make
> our life easier. I haven't tested yet. It's not so important for html
> - but for print?! Order matters!

Already discussed above, don't add support for subdocuments or let 
authors be free to choose whatever file name they want and let them use 
built-in reST commands to integrate them. But I'd prefer not allowing it 
for the time being, concentrate on the remaining questions and allow it 
at some further point if it proves that it would be really better for 
the documentation.

For Core documentation, I'm fine of course to use the full power of reST 
and split the big documentation into smaller parts but for 99% of the 
extensions, this is not really needed I'd say.

Cheers

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org