Jan 27, 2015 Tags: TYPO3, T3Docs

TYPO3 Documentation Tips

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

Updated on Nov 11, 2015

Navigate this page:

FAQ: TYPO3 Documentation

Frequently asked questions

Q: How can I insert a line break (<br />)?

A: You can’t ...

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

looking into a sample Settings.yml

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 at Forge

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

  1. Please do escape some characters in normal flowing text:

    |    ->     \|
    *    ->     \*
    _    ->     \_
    \    ->     \\
    
  2. Do not escape any characters in code-blocks or literal-text!

  3. There must be a blank line after a .. code-block:: directive

  4. 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!

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

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

  1. ((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.))
  2. And BTW, there’s no ”..” after the code block.
  3. Don’t wrap lines inside code blocks. Let the rendering manage it.
  4. For lists, we use “-” instead of “*”, although the latter works fine too.

Martin’s preferences

  1. 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
    
  2. 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.

Sphinx and Read the Docs

ReadTheDocs

More:

Comments

comments powered by Disqus

Previous topic

Sphinx-Doc Installation Steps

Next topic

Kochen und Rezepte

Tags

Archives

Languages

Recent Posts

This Page