[TYPO3-english] [explanation] Broken property tables on docs.typo3.org

[Xavier Perseguers]

Hi,

Laurent Foulloy, author of extension sav_jpgraph contacted me yesterday
regarding a problem he had with his documentation and the rendering of
"property tables". See [1] and compare with [2]. The point is that when
using EXT:sphinx locally, rendering is fine, when uploading to TER, not.

As I'd like everyone to know the outcome of the discussion, I'm posting
my answer here, so that it benefits to you as well.

First of all, you have to know that for the time being the actual
rendering of your extension manual may take a few hours, so don't worry if

a) The manual does not show up as soon as your uploaded extension is
visible on TER

b) The link to the manual is (still) pointing to a former version

=> Chances are very high that you just have to wait a bit!

Now, back to the "problem" of those property tables.

We quickly discussed the problem yesterday during our doc-team meeting.
Martin Bless told me he would investigate a bit however it seems that
you simply did not stick to using the proper list of "key-value" (you
have "Tag" as a key in your samples but "Tag" is not recognized and does
not trigger the rendering, at least that's what turned out by quickly
looking at your doc).

Why does it work with EXT:sphinx? I guess you tested by using the
"Interactive" layout, and not the "static" one, right? Static will
render "exactly" as on docs.typo3.org, as static HTML, whereas
"Interactive" will render as JSON and integrate it into a layout similar
to docs.typo3.org but that lets you edit any chapter and recompile on
the fly. JSON output is unfortunately not properly supported by our
"enhancements" we made to Sphinx-Doc to support e.g., those "special
tables". As such, I mimic-ed the rendering by post-processing the output
and "re-render" the property tables as on docs.typo3.org. However, my
code does not care about a list of supported key-values, instead it is
more generic and as such "better" if you want.

We may/could probably enhance the Sphinx-parser on docs.typo3.org but
the point is that those property tables are somehow deprecated and not
the (best) way to go anymore. One of the points is that PDF output is
really ugly and we would like to come-back as much as possible to
"vanilla sphinx-doc". Unfortunately the auto-convertor from OOo ->
Sphinx renders such (deprecated) property table markup.

The way we advertise to go is to do it like that instead: [3] (please
see source code).

Hope this will be of some help to everyone.

Cheers


[1]
http://docs.typo3.org/typo3cms/extensions/sav_jpgraph/Reference/Callback/Index.html

[2]
http://docs.typo3.org/typo3cms/TyposcriptReference/DataTypes/Htmlcode/Index.html

[3]
http://docs.typo3.org/typo3cms/extensions/restdoc/1.3.2/Configuration/TxRestdocPi1/Index.html

-- 
Xavier Perseguers
TYPO3 CMS Team Member

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