[TYPO3-dev] ReST documentation from extensions

[Dirk Wenzel]

Hi,
I am not shure whether or not somebody already mentioned it:

As an extension developer, I want to:
- maintain only one version (ReST) of documentation
- have an opportunity to inspect the rendering results (as this is the 
most cumbersome part for me in writing documentation nowadays: I was 
never able to predict what my changes in manual.sxw did to the online 
version. There could be a service which renders a preview for both pdf 
and html version)

As an integrator, I want to have an up-to-date configuration manual of 
each extension available in the backend.

(And I don't want any undocumented extension in my system nor any 
documentation scattered over a bunch of shiny fancy private/corporate 
websites as this is more and more the case -> for documentation see 
website xyz.com)

As an editor, I want to have an up-to-date user manual of each 
(relevant) extension available in the backend.

As a developer, I want to have an up-to-date api-documentation of each 
extension (online?).

Cheers
Dirk

Am 05.04.13 10:58, schrieb 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
>