Jan 27, 2015 Tags: TYPO3, T3Docs
Tips to become a happy TYPO3 documenter. This post will be updated as needed.
Updated on Nov 11, 2015
Navigate this page:
Frequently asked questions
startFolder/Documentation/. There needs to be at least the start reST file
As an alternative you can use a ./README.rst in the root folder of your extension.
It will be rendered on docs.typo3.org, but ONLY if there is
Github and Bitbucket render and display that file as well.
In other words: a ./README.rst will be ignored by documentation rendering on docs.typo3.org if regular documenation in PROJECT/Documentation/Indes.rst exists.
./README.mdinto the startfolder. On docs.typo3.org the converter Pandoc is installed and will convert from markdown to reSt first. This conversion isn’t always perfect. As before: a ./README.md will be ignored by documentation rendering on docs.typo3.org if regular documenation in PROJECT/Documentation/Indes.rst exists.
Rendering happens automatically:
An upload to the TER (TYPO3 Extension Repository) will automatically trigger documentation rendering on http://docs.typo3.org It should afterwards be listed at http://docs.typo3.org/typo3cms/extensions Try the autocompletion! Usually rendering takes place every thirty minutes at HH:00 and HH:30.
Tip: Be patient! After uploading an extension to the TER (TYPO3 Extension Repository) at http://typo3.org it may take up to 3 or 4 hours until the extension is fully processed. This applies to the extension’s documentation as well.
If the documentation doesn’t appear:
Make sure you don’t have a fatal error in your reST files as in this case you won’t get a result and with the current rendering chain this happens silently. You don’t get any notification.
Do I have errors in my reST markup?
If the rendering process did not stop prematurely there should be a
in the root folder of the rendered documentation.
Warnings and non-fatal errors of reST rendering are reported there. If that file is
empty this means: The reST source is perfect - we don’t have errors and warnings.
Something else wrong? Get in contact!
Another reason for not getting output can be a problem with the rendering chain. If you think that’s happening get in contact with the documentation team. The most effective way is to create an issue at Forge at “Documentation Rendering”:
Inspired by post [TYPO3-core] Common reStructuredText mistakes in “core” Changelog
Please do escape some characters in normal flowing text:
| -> \| * -> \* _ -> \_ \ -> \\
Do not escape any characters in code-blocks or literal-text!
There must be a blank line after a
.. code-block:: directive
Don’t use arbitrary text roles like
not recognized. Simply use “
:code:`...` defaults to just `...`
if the default-role is set to code. You can set and change the default-role at any point in your documentation with the default-role directive:
.. default-role:: php .. default-role:: rst .. default-role:: code Default role is code now. So you can just write `$sum = 1 + 2;` instead of :code:`$sum = 1 + 2;`
Tip: Most TYPO3 manuals already have that line
.. default-role:: code in their
Includes.txt file. If not - add it!
Don’t put white spaces before list markers:
Here we go our lovely having this list: - a - b ^^ wrong!
Here we go our lovely having this list: - a - b Perfect!!
Note: Lines starting with arbitrary white spaces will be rendered as block quotes.
_ccc_ is not a valid inline markup. Use
:code:`ccc` for code or
:code:`put code here` -> will have some special font and style *emphasize me* -> usually displayed as italics **strong emphasis** -> usually displayed as bold
Make use of the default-role:
.. default-role:: code `put code here` -> will have some special font and style
And now some best practices used by the Documentation Team:
You can always switch the default highlighting and the default role in your document:
.. highlight:: rst .. default-role:: code Write inline code like this. Will always work, because we specify the text-role explicitely:: :code:`$value = 'a string';` Write inline code like this. Will work, if we've seen a `.. default-role:: code` before, because we rely on a proper default role setting: `$value = 'a string';` .. highlight:: php Here's some PHP:: phpinfo(); .. highlight:: bash Now we are prepared for shell code:: echo "Be happy - be highlighted" ls -la
And then it’s nice to start code blocks smoothly:
:: at the end of a sentence starts a code-block and is shown itself as one colon:
Now we show a line of code:: $variable = 'one';
A :code:` ::` (note the blank!) at the end of a sentence starts a code-block but doesn’t show a colon:
What do you think of this line of code? :: $variable = 'two';
:: in a line of itself starts a code-block but doesn’t show up in the output:
What do you think of this line of code? :: <- line is removed from output <- line is removed from output $variable = 'three';
This is the solution you can always use which is why it is common in the automatically generated documentation.
Getting Started with ReadTheDocs. Recommends the following video:
Video introduction “Sphinx & Read the Docs”. At minute 14:15: How do we get that documentation to ReadTheDocs?
The video highly recommends socrates.io.