[TYPO3-dev] ReST documentation from extensions

[Xavier Perseguers]

Hi Francois,

> I think that what we should really have is an extension which achieves
> the following goals:
> 
> - fetch the manuals from docs.typo3.org, formats to be discussed (PDF is
> really fine for offline perusal, HTML could be browsed directly from
> within the TYPO3 BE).
> - as a fallback, display ReST as a simple text file.

That sounds very good and apart from displaying ReST as a simple text
file (because although it sounds easy we would then have to support
multiple source files as well if the documentation is split...) this is
an extension that seems quite easy to implement as we already have the
language sysext as template.

We could think of only supporting recent versions of TYPO3 (6.x), it's
even easier.

> This extension would make it possible to fetch all manuals, in the
> chosen formats. If all manuals are stored in a specific folder (to be
> decided upon), it would be easy to perform the download on an
> Internet-connected install and copy the stuff over to a "disconnected"
> server.

And once we have a concept to translate documentation, we could even
reuse the language sysext, meaning we could think of extending it right
away with a checkbox like "fetch manuals".

But as you say, the problem is not this extension nor where we would
store those manuals...

> The problem we (= the Documentation Team) are facing is the lack of
> resource (as usual, but quite acute in this case). We are really only
> 3-4 people active at best, with a lot to do. I would very much like the
> PDF rendering to be completed, for example, but there's absolutely no

What about a sprint during T3DD?

> one to tackle that. We don't even yet have a properly automated
> rendering chain for manuals, we can't yet detect automatically if an
> extension has OO- or ReST-based documentation, etc.

Perhaps I miss something but I'd say that this could be easily done:
"/doc" is for OO-based, "/Documentation" is for ReST and would fit the
new extension directory structure we see more and more nowadays. As
virtually nobody really started to write ReST-based documentation, this
breaking change could easily be imposed.

Cheers

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

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