[TYPO3-core] ReStructured Text in the TYPO3 backend

[François Suter]

Hi all,

Here's the promised second mail (result of the brainstorming session I 
had on Friday with Xavier and Dominique).

Once we have converted the sysext manuals to ReST, we will have a 
complete ReST-based documentation infrastructure available, since 
official manuals are already in ReST and extension manuals are 
automatically converted (although with a lower quality of result than if 
they are natively written in ReST).

So we must think about how to handle this in TYPO3 CMS, in the backend 
in particular. The 6.+ Extension Manager dropped the link to the 
OpenOffice file, but it doesn't mean that documentation shouldn't be 
accessible anymore. On the contrary, it is an opportunity to build 
something more useful.

First and foremost is what to do to enable visualization of the 
documentation, since although ReST is readable, it is not convenient to 
do so. We can of course simply provide a link to the online, rendered 
version, but it is not sufficient, since some TYPO3 installations do not 
have access to the Internet. Some possible scenarios:

- package rendered documentation with the Core. Possible, but does not 
address all cases, since it doesn't cover extension manuals.
- offer some download possibility. The same problem exists without 
Internet connection, but at least the whole documentation can be 
retrieved from some other machine and uploaded to the server.
- provide local rendering facilities. This is possible as Xavier has 
demonstrated with his "Sphinx" extension [1]. It requires to have Python 
on the server and - of course - Sphinx installation won't work (again) 
if the server is not connected to the Internet.
- possibly other ideas can come up during the discussion.

What we thought for sure is that we should define a place where rendered 
documentation is expected to be. This way any backend module that relies 
on documentation would know where to find it, no matter how it was made 
available on the server.

The question of format also came up. To really integrate with the BE, 
the JSON format seems the most useful, as it provides separate bits for 
each documentation page (i.e. the main content, the local navigation, 
the breadcrumb, etc.). We could possible use the HTML format, but it 
would require extracting the content and each other part of the page 
that we want to use and is thus less convenient. However we currently 
have issues with JSON rendering, due to subclassing some Python code 
somewhere during the rendering. We currently do not render PDF format, 
although we certainly would like to. This would also be useful for local 
browsing.

Examples of JSON format usage can be found both in Xavier's "restdoc" 
extension [2] and in the TYPO3.DocTools Flow package [3].

Anyway there needs to be some extension managing this: display, possibly 
retrieval too. Would it be the Extension Manager? Or a separate 
extension? Probably the latter is better, since language package 
retrieval was already separated. It would provide a module to view all 
available documentation and make it possible to retrieve it (and also 
provide a Scheduler task for it I guess (probably better packaged as an 
Extbase command controller)). It would be or not be integrated with the 
EM to provide links to documentation there.

Going with further ideas we thought it would be nice to provide an API 
for linking to a particular piece of documentation in the TYPO3 backend. 
This could provide some kind of enhanced CSH or maybe even replace it 
over time. It would certainly make it easier to maintain system 
extension "cshmanual". It could also provide a menu in the top bar with 
links to "favorited" documentation (could be customized per user or user 
group).

That's quite a bit of food for thought already. I'm looking forward to 
your feedback and ideas in order to draw plans for a really cool usage 
of ReST in the TYPO3 backend.

Cheers

-- 

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

[1] http://typo3.org/extensions/repository/view/sphinx/
[2] http://typo3.org/extensions/repository/view/restdoc/
[3] https://git.typo3.org/FLOW3/Packages/TYPO3.DocTools.git