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
See also
Navigate this page:
Frequently asked questions
At least not by “ordinary” means. The reason for this is that reST is designed for structural (semantic) markup and a line break belongs to the layout. Try to find another way. Sometimes line-blocks come in handy.
Where do I find the basics of reST markup?
How do I get the “Edit me on GitHub” button?
((to be written))
settings for this to your Settings.yml
file:
conf.py:
html_theme_options:
github_repository: GithubUser/Project
github_branch: master
Example: See the Settings of the TYPO3 Coding Guidelines:
How can I link in my documentation project from one point to another?**
Normal Docutils hyperlinks work. The means:
You can link from ABC_ to _ABC
Crib: Doesn’t this look like ABC-> pointing to ->ABC? Looks like an arrow pointing to a landing platform.
If it’s more than one word:
Link from `Good News`_ to _`Good News`
Give the hyperlink target a name (= label). The label is alphanumeric plus “-_” (minus, underscore). Case does NOT matter. Pick a headline in the target document and give it a target name:
.. _This-is-the-FAQ:
====================================
FAQ - Frequent Answers and Questions
====================================
See ‘Rules For Names Of Link Targets’.
Create a link to the target bei using the :ref:
textrole:
We recommend to read the :ref:`this-is-the-faq`
As a result you’ll get:
We recommend to read the FAQ - Frequent Answers and Questions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
linked text is that of the target
If you want to use your own linktext:
We recommend to read the :ref:`very useful FAQ! <this-is-the-faq>`.
Let’s say your project is http://docs.typo3.org/typo3cms/extensions/rlmp_language_detection/. Now you want to link to the FAQ from some other Sphinx project.
In that case you can write:
We recommend to read the :ref:`rlmpld:this-is-the-faq`
What does this rlmpld
mean? It’s an arbitrary shortcut you can choose.
To make it work add a definition to conf.py
, or, for TYPO3
projects, Settings.yml
:
In Settings.yml:
conf.py:
intersphinx_mapping:
rlmpld:
- http://docs.typo3.org/typo3cms/extensions/rlmp_language_detection/
- null
If you want to use your own linktext:
We recommend to read the :ref:`very useful FAQ! <rlmpld:this-is-the-faq>`.
What are the rules for creating link targets?
Find a headline you want to create a target to
Insert a line before that headline that looks like .. _TEXT-OF-THE-LABEL:
Samuel Morse would have memorized that as “dot, dot, blank, underscore, TEXT, colon”
Use only A-Z, a-z, 0-9, “-”, “_” for the Label. No blanks!
Labels are CASE INSENSITIVE. So you CAN use uppercase letters.
So you will probably prefer .. _addParams-Examples:
instead of
.. _addparams-examples:
.
How can I find out what link targets exist?
.. ref-targets-list::
directive¶Tip: Try the .. ref-targets-list::
directive!
This single line directive creates a list of all the reference targets you have in you project. And that can be quite impressive! As an example see the list of targets of TypoScript reference and compare this to the very short source of that page.
The good thing about this directive is that you as the author tell everybody else in the world which targets in your documentation project you provide and consider stable. And of course: You should keep them stable!
Tip: If you feel a label is outdated and you would much more use a different one: Think twice before you change it. Instead: ADD the label you like as an additional one!
startFolder/Documentation/
. There needs to be at least the start reST file
./Documentation/Index.rst
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
no ./Documentation/Index.rst
.
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.md
into 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 warnings.txt
in the root folder of the rendered documentation.
Example: http://docs.typo3.org/typo3cms/TCAReference/warnings.txt
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 :php:
or :javascript:
. These are
not recognized. Simply use “...
.
Tip
: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!
Instead write:
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 *ccc*
for emphasis:
: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:
A ::
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';
A ::
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.
https://code.google.com/p/gerrit/source/browse/Documentation/config-hooks.txt 2015-04-10
ReadTheDocs
A New Theme for Read the Docs. Blogpost by Eric Holscher, 2013-11-04
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.
More: