Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Tips and Tricks (reST)

From TYPO3Wiki
Jump to: navigation, search

This chapter aims at providing helpful hints, tips and tricks that make your life with reST and the writing of documentation easier. As usual, please feel free to contribute your own tips and tricks here!

Building Documentation

If you think preparing your environment for Sphinx is complicated, or you would like to render on your webserver but do not have proper shell access to set up the Python environment, you should try the TYPO3 extension Sphinx (tag 0.0.1 is compatible with TYPO3 4.5-4.7)

Embedding Documentation into your Website

If you want to embed your reST documentation into your website, you basically have 4 possibilities:

  1. Generate a PDF (documentation link needed) and link to it
  2. Generate a HTML page/website out of your reST documentation, possibly changing the HTML template (documentation link needed)
  3. Use the TYPO3 extension restdoc, Use case: [1]
  4. Publish your documentation using an external (free) service: https://readthedocs.org/

Cross-Links

Sphinx lets you create links to other documentation projects; this feature is called "intersphinx".

To use it, open conf.py and load module intersphinx:

extensions = ['sphinx.ext.intersphinx']

Then, you need to reference every possible external manuals you would like to possibly link to (at the end of conf.py). The list of official TYPO3 manuals is:

intersphinx_mapping = {
    't3extbasebook': ('https://docs.typo3.org/typo3cms/ExtbaseFluidBook/', None),
    't3l10n':        ('https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/', None),
    't3install':     ('https://docs.typo3.org/typo3cms/InstallationGuide/', None),
    't3security':    ('https://docs.typo3.org/typo3cms/SecurityGuide/', None),
    't3cgl':         ('https://docs.typo3.org/typo3cms/CodingGuidelinesReference/', None),
    't3api':         ('https://docs.typo3.org/typo3cms/CoreApiReference/', None),
    't3fal':         ('https://docs.typo3.org/typo3cms/FileAbstractionLayerReference/', None),
    't3inside':      ('https://docs.typo3.org/typo3cms/InsideTypo3Reference/', None),
    't3skinning':    ('https://docs.typo3.org/typo3cms/SkinningReference/', None),
    't3tca':         ('https://docs.typo3.org/typo3cms/TCAReference/', None),
    't3tsconfig':    ('https://docs.typo3.org/typo3cms/TSconfigReference/', None),
    't3tsref':       ('https://docs.typo3.org/typo3cms/TyposcriptReference/', None),
    't3tssyntax':    ('https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/', None),
    't3services':    ('https://docs.typo3.org/typo3cms/Typo3ServicesReference/', None),
    't3editors':     ('https://docs.typo3.org/typo3cms/EditorsTutorial/', None),
    't3start':       ('https://docs.typo3.org/typo3cms/GettingStartedTutorial/', None),
    't3templating':  ('https://docs.typo3.org/typo3cms/TemplatingTutorial/', None),
    't3ts45':        ('https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/', None)
}

Within your own documentation, just prefix a link with one of the external manual label. E.g.,

Sphinx makes it easy to link to official TYPO3 documentation:

- :ref:`TYPO3 Tutorial for Editors <t3editors:start>`
- :ref:`Getting Started Tutorial <t3start:start>`

and you may even link to a very specific chapter explaining how to :ref:`create a browser condition
<t3tsref:condition-browser>` within the TypoScript Reference.