[TYPO3-doc] Experiences with ReSTructured Text

[François Suter]

Hi Sebastian,

Thanks for your answers.

> First, it is very simple to generate any desired HTML URL. Basically,
> there is an *1:1* mapping between input and output documents. So, if you
> have the input ReST document structure of:
> [snip]
> In order to include other files, there is the "Table of Contents" tree
> directive, looking like:
>
> http://git.typo3.org/FLOW3/Documentation.git?a=blob;f=TheDefinitiveGuide/Index.rst

That sounds pretty good.

> Not out of the box, as it seems, but we can create a simple python
> script which we can use for that:
>
> http://groups.google.com/group/sphinx-dev/browse_thread/thread/ef92ffdf7aff6191
>
> ... or even do some more fancy visualization :-)

I can't say that I really understood the snippet you're pointing too, 
but I have no doubt that it's feasible anyway. I was just thinking that 
i could be useful, especially for extension developers, to have an 
overview of all the links they can do (even if they could simply take 
them from the existing documentation).

> As said, there are two ways of generating PDF: one using LaTeX and one
> using rst2pdf. Here are example outputs:
>
> LaTex: http://sphinx.pocoo.org/sphinx.pdf
> rst2pdf: http://sphinx.pocoo.org/sphinx-rst2pdf.pdf

Both examples look pretty good, the LaTeX one a bit better.

> but we should also test the
> other one and see how difficult/easy the adjustments are.

Definitely.

> IMHO the build chain is a *lot* easier to set up, as it is just one
> easy_install command; and we can use the standard Sphinx build chain; no
> custom Phing / Bash / XSLT stuff needed... I once tried to write some
> Phing scripts for installing a DocBook build chain and setting it up
> correctly; and it was quite complex IMHO...

OK. Good to hear.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch