[TYPO3-dev] ReST documentation from extensions

[Xavier Perseguers]

(cross-posting to dev and documentation lists, please answer in dev list)

Hi,

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

We have a few possibilities:

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

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

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

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

5) Locally render the documentation

.) ...


For 4) I thought (did not implement anything) that we could reuse 
EXT:restdoc this way:

- Compile as JSON
- Post-process to change references to images to reuse the ones within 
sources
- Only include JSON content (not the images), and index files, ...
- Would minimize the additional payload
- Could be done on TER (but again, I dislike having my extension 
externally modified)

For 5) I don't know if having an extension with "Sphinx environment 
included" would be possible and only require python to be available 
(which is very likely on most servers anyway, at least Linux-based), and 
I did not check what the resulting payload would be, otherwise we have 
an alternate yet much more basic solution by parsing reST in PHP.

A project has been created years ago:

http://code.google.com/p/php-restructuredtext/

If you want to give it a try, contribute, see where it leads, you may 
join forces on this branch I just kickstarted:

http://forge.typo3.org/projects/extension-restdoc/repository/show/branches/Backend

I really don't know if it's viable at all but just in case...

Cheers

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

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