TYPO3 Documentation Tips¶

Tips to become a happy TYPO3 documenter. This post will be updated as needed.

Updated on Nov 11, 2015

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.

Q: Basics of reST markup?¶

Where do I find the basics of reST markup?

A: Some pointers ¶

This is a great reStructuredText Primer:
https://wiki.typo3.org/ReST_Syntax
https://docs.typo3.org/typo3cms/drafts/github/xperseguers/RstPrimer/ See the (Repository)

Q: “Edit me on GitHub” button?¶

How do I get the “Edit me on GitHub” button?

A: Since Oct 2015 ¶

((to be written))

A: Before Oct 2015 ¶

You can do it all by yourself. Just add the configuration

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:

Q: How To Create Hyperlinks?¶

How can I link in my documentation project from one point to another?**

A: Hyperlinks within the same file ¶

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`

A: Hyperlinks between Files of the same Project ¶

Name the target ¶

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’.

Link to the target ¶

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>`.

A: Link to a foreign documentation project ¶

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>`.

Q: Rules For Names Of Link Targets?¶

What are the rules for creating link targets?

A: The Rules ¶

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:.

Q: What Link Targets Exist?¶

How can I find out what link targets exist?

A: Think of the `.. 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!

Q: Menu Hierarchy ¶

What do I need to know about creating a proper menu hierarchy?

A: The `.. toctree::` directive is the key!¶

At least with the new theme you can have up to six levels or so in the left menu. So you CAN have easy and deep navigation. Note: Folder levels on disk have NOTHING to do with menu levels. Instead, each .. toctree:: directive creates a new menu level.

Keep in mind: Each .. toctree:: creates a new menu level!

Q: Help! I hate ‘### BEGIN~OF~TABLE ###’!

Editing those ‘### BEGIN~OF~TABLE ### ... ### END~OF~TABLE ###’ blocks is a pain.

A: What can I do?

These blocks have never been meant to be edited by a human. They are the result of the automatic conversion process from OpenOffice format to reStructuredText.

What should be done is this: Find a different way to express what you want to say using “normal reST writing style”. Here is an example of how this could be achieved:

Try to find an even better way!

Documentation in your TYPO3 CMS extension ¶

Worst: No documentation

To have no documentation at all really is a bad idea. There’s no excuse for this.

Best: Full documentation in ./Documenation/Index.rst

Add a full featured documentation to your extension in startFolder/Documentation/. There needs to be at least the start reST file ./Documentation/Index.rst

Second best: ./README.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.

Third best: ./README.md

Put a markdown ./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.

Learn more: Add documentation for Extensions

Read this chapter Adding documentation to learn about adding documentation to a TYPO3 CMS extension.

About the rendering:¶

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”:

Create an issue if something is not working and to get in contact with the TYPO3 Documentation Team.

Tips for the TYPO3 Core Developer ¶

Turn a logfile into valid reStructuredText ¶

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

Best practises ¶

And now some best practices used by the Documentation Team:

((needs more explanation, is not true in this form:))((Avoid using ”::” for code blocks, better use the ”.. code-block::” directive, because you can define the language for syntax highlighting.))
And BTW, there’s no ”..” after the code block.
Don’t wrap lines inside code blocks. Let the rendering manage it.
For lists, we use “-” instead of “*”, although the latter works fine too.

Martin’s preferences ¶

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.

Mac ¶

ScreenFlow (Tweet), Camtasia,

Screenshot software ¶

Screenshots of complete web pages
There is Screenflick for OS/X

To be sorted ¶

What is the difference: reST, docutils, sphinx, readthedocs <https://coderwall.com/p/vemncg/what-is-the-difference-rest-docutils-sphinx-readthedocs>`__
reST, Docutils and Sphinx
PEP 287 - reStructuredText Docstring Format
Rustdoc: reStructuredText vs Markdown
http://blog.codinghorror.com/the-future-of-markdown/ Etherpad!?

Sphinx and Read the Docs ¶

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:

TYPO3 Documentation Tips¶

Quick search

Previous topic

Next topic

This Page