[TYPO3-dev] Rendering on docs.typo3.org

[Xavier Perseguers]

Hi Francois,

>>> What I did not do: properly render OOo-based manuals as it involves
>>> >  multiple Python-based scripts which I never used myself and they are
>>> >  still rendered on typo3.org anyway so this part will wait!
>>
>> This is now done, I could not stand anymore seeing TER linking to awful
>> rendering on docs.typo3.org.
> 
> Woohoo! Thanks for everything!

You're welcome :)

A few info for everyone:

- OOo-based manual may be converted to Sphinx project using either
EXT:sphinx (dashboard in Help > Sphinx Documentation Viewer) or online
service from Documentation Team:
http://docs.typo3.org/getthedocs/service-convert.html (this is exactly
the same!)

	1) After the conversion, please first convert every .gif image to
either .png or .jpg (and adapt inclusion) because .gif is not compatible
with PDF rendering
	2) Adapt the Index.rst start page using this template:
http://docs.typo3.org/typo3cms/extensions/sphinx/_sources/Index.txt
	3) Test the rendering locally, it's so damn easy with EXT:sphinx

- Many "recent" extensions have been kickstarted with the Extension
Builder which automatically created an example documentation (based on
the official template back then). It was meant as a base to be updated
or deleted if you did not want to have a Documentation at that time but
many authors just left this dumb documentation in place. This is now
fixed in recent version of EB. In order to prevent us for cluttering
docs.typo3.org with those actually invalid manuals, I detect if this is
the case (or seems to be!) and if so, I simply skip its rendering!

- You *must* have a Settings.yml file in your Documentation/ folder
(EXT:bib currently does not for instance, don't know why, probably
because it was manually kickstarted) otherwise it will be as if you
would not have any documentation for your extension

- You /should/ update the version (upcoming one) of your extension in
Settings.yml prior to uploading it to TER because it is used on
docs.typo3.org to show the manual's version. However, as it is easily
forgotten I override it anyway when rendering, based on the actual
extension's version

- As Sphinx-based documentation are now automatically rendered, it would
be good if the Documentation module from TYPO3 6.2 would be largely put
under stress. It has been developed a while ago, we did not change much
and hopefully kept compatibility but it is time to adjust it if needed:

	1) fetch of official documentation

	2) fetch of offline copy of installed extension's manual - only if
Sphinx-based - another excellent reason to switch today to Sphinx for
your extension manuals

	3) behaviour of this fetch when a multilingual documentation is found
according to the Backend user language (fix or enhance UX if needed)

	4) Known multilingual extensions: EXT:in_gallery_flickr,
EXT:socialshareprivacy, EXT:sphinx


I really encourage you to read chapter of EXT:sphinx's manual regarding
what to know about rendering on docs.typo3.org:

http://docs.typo3.org/typo3cms/extensions/sphinx/UsersManual/DocsTypo3Org/Index.html

Just so that you get the most out of it!

Cheers
Xavier

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

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