[TYPO3-dev] Extension documentation in ReST format

[François Suter]

Hi Tolleiv,

> actually this assumption is imho wrong. THe documentation team has
> hardly managed to build up their services, but we (T3O-Team + Doc-Team)
> haven't been able to integrate both "services" properly by now. There
> hasn't been any kind of official announcement that ReST should be used
> for extensions. Once you start using it for your extension you'll break
> usability for typo3.org users, because nobody would be able to reach
> your documentation through the normal search etc...

Yes, that's right. I think this integration should be the aim of the 
next code sprint, so that extension authors can switch safely. Since we 
can also transform OpenOffice manuals to ReST (and then to HTML again), 
we have all extension manuals on docs.typo3.org. The most important next 
step IMO is to change the links from the TER to docs.typo3.org. Of 
course, this also means changing the detection of an existing manual. 
Indeed if there's neither an SXW file, nor ReST files, the documentation 
should be marked as missing, as is done now.

An extra step, but one we are not ready for yet, would be to trigger the 
rendering of the manual when an extension is uploaded. We don't have the 
endpoint on docs.typo3.org yet and neither is the TER ready for it. We 
currently rely on a cron running on docs.typo3.org.

But it's still a good sign that some developers start adopting REST I 
think, even if it may create an awkward situation for users. Hopefully 
it could help "bring back to the fold" developers who chose an entirely 
separate solution (for example, Claus Due, who has developed a lot of 
clever extensions, has included no documentation for the; it is all 
located on his own web site). It's clearly better than having no 
documentation, but it's also a shame that it exists outside the global 
scheme.

Cheers

-- 

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