[TYPO3-dev] ReST documentation from extensions

[François Suter]

Hi Xavier,

> We still don't have solution to read reST-based documentation from
> extensions within the Backend.

Indeed. The problem is actually even more pressing, because it prevents 
us from migration system extension manuals to ReST. This is something 
which we have already postponed for 6.0 and 6.1, but that I would really 
like to see happen for 6.2.

> 1) Do nothing: ask the author to put a PDF or OOo as well

OO definitely not ideal, as we would like to drop usage of that format 
entirely. I doubt that extension authors would appreciate going to the 
extra trouble of generating a PDF.

> 2) Generate a PDF on TER while uploading the extension and "repackaging
> it" (don't like it but possible)

It's not ideal, but it's something I thought about already.

> 3) Show the online HTML version (won't work for Intranet disconnected
> from "the world")

"Disconnected" intranets have indeed been mentioned as an issue already 
in the past.

> 4) Ask the author to provide a HTML version as well

Just as for providing a PDF version, that would probably not go down 
well with extension authors.

> 5) Locally render the documentation

This is very unlikely. I could imagine that we could have some basic 
rendering, but very unlikely that we could have all the existing 
features of Sphinx.

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.

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.

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 
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.

So it would be good if those who find this discussion interesting also 
considered whether they can help or not, otherwise I'm afraid the topic 
will stay strictly theoretical for a while more.

Note: this is not meant to kill the discussion or to make indirect 
reproaches at anyone. Just a reality check ;-)

Cheers

-- 

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