Rendering on docs.typo3.org¶

Title, copyright and version¶

A valid Sphinx project for an extension manual should contain a configuration file Settings.yml next to the main document Index.rst. This file is your key to override default settings from the real Sphinx configuration file conf.py which is not part of your project (because it contains settings related to the build environment on https://docs.typo3.org). Instead, this YAML configuration file lets you define project options.

This extension takes care of loading options from Settings.yml as well, thus ensuring a smooth experience when working locally on your extension manuals before their automatic deployment to https://docs.typo3.org.

A basic Settings.yml file should define a few basic project information:

1
2
3
4
5

conf.py:
  copyright: 2013-2015
  project: Sphinx Python Documentation Generator and Viewer
  version: 2.3
  release: 2.3.0

project

The documented project's name.

copyright

A copyright statement in the style 2017, Author Name.

Tip

Within TYPO3 official documentation, we usually only show the year(s) of copyright, e.g., 2017 or 2010-2017.

version

The major project version, used as the replacement for |version|. For example, for the TYPO3 documentation, this may be something like 6.2.

release

The full project version, used as the replacement for |release|. For example, for the TYPO3 documentation, this may be something like 6.2.0rc1.

If you don't need the separation provided between version and release, just set them both to the same value.

Tip

This is of course up to the extension's author to decide on a version numbering scheme but best practices follow the same rules as for TYPO3 core and do not introduce breaking changes or new features in patch-release versions (when the last of the three digits changes).

As extension authors are very likely to forget to update the version prior to uploading their extension to TER, the rendering engine on https://docs.typo3.org automatically overrides the version and release parameters to the actual version as seen on TER.

PDF rendering¶

The PDF of your documentation is rendered using the LaTeX builder from Sphinx (see Rendering PDF from reStructuredText if needed) and should be explicitly activated for your extension. To do so, open file Settings.yml (at the root of your documentation folder) and make sure it contains following configuration options (lines 6 to 15):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

conf.py:
  copyright: 2013-2015
  project: Sphinx Python Documentation Generator and Viewer
  version: 2.3
  release: 2.3.0
  latex_documents:
  - - Index
    - sphinx.tex
    - Sphinx Python Documentation Generator and Viewer
    - Xavier Perseguers
    - manual
  latex_elements:
    papersize: a4paper
    pointsize: 10pt
    preamble: \usepackage{typo3}

Lines 7 to 11 define options for value latex_documents which determines how to group the document tree into LaTeX source files. This is a list of tuples: startdocname, targetname, title, author, documentclass, where the items are:

startdocname

Document name that is the "root" of the LaTeX files. All documents referenced by it in TOC trees will be included in the LaTeX file too.

Warning

Always use Index here.

targetname

File name of the LaTeX file in the output directory.

Warning

Always use your extension key followed by .tex here.

title

LaTeX document title. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.

author

Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \and to separate multiple authors, as in: 'John \and Sarah'.

documentclass

Normally, one of manual or howto (provided by Sphinx).

Tip

To keep TYPO3 branding, you should always use manual here.

Lines 12 to 15 should be kept as-this. Line 15 is actually the "trigger" for PDF rendering.

When activated, your PDF gets automatically rendered on https://docs.typo3.org under https://docs.typo3.org/typo3cms/extensions/extension-key/_pdf/. E.g., https://docs.typo3.org/typo3cms/extensions/sphinx/_pdf/.

Please read chapter Customizing the rendering for further information on LaTeX configuration options.

Multilingual documentation¶

Multilingual exension manuals are supported by both this extension and https://docs.typo3.org. If you want to translate your documentation, kickstart a new Sphinx project (incl. Settings.yml) within directory Documentation/Localization.locale.

Best practices¶

When translating a documentation, you may be tempted to translate everything, including directory and file names. Although this sounds reasonable at first sight, we advise you not to do so.

In fact, best practices show that if you keep the original directory and file names, you let readers quickly switch back and forth from a chapter to its translation on https://docs.typo3.org because the language switch (currently hidden in the "version" dropdown) simply searches for the same relative URI in the translated documentation. If it finds the same document, it will go to the very same chapter (but translated!) otherwise it will go to the start page.

This is depicted by the following figure. The second navigation bar (French documentation) shows that directory and file names have been preserved. It is thus possible to switch from the original, in English, to the French translation by prefixing the URI segment fr-fr/. In the third navigation bar however, the directory and files names have been translated as well, making it impossible to match chapters with their translated counterparts:

Cross-link to other documentation¶

Sphinx lets you easily cross-link to other documentation such as official manuals and guides or extensions' manuals (granted that they have been written with Sphinx and not in OpenOffice) by prefixing the link target appropriately.

A construction like :ref:`stdWrap in details <t3tsref:stdwrap>` will create a link to the stable version of the official TYPO3 "TypoScript Reference", within chapter "stdWrap":

• stdWrap in details

Behind the scenes, this works as follows:

• Each Sphinx HTML build creates a file named objects.inv that contains a mapping from object names to URIs relative to the HTML set’s root.
• Projects using the Intersphinx extension can specify the location of such mapping files in the intersphinx_mapping config value. The mapping will then be used to resolve otherwise missing references to objects into links to the other documentation.

The list of official manuals and corresponding prefixes may be found on https://docs.typo3.org/typo3cms/Index.html.

.. _start:

===================================
Title of your extension
===================================

You may link to any other documentation on https://docs.typo3.org (or elsewhere) by configuring the Intersphinx mapping within Settings.yml. To do so, add configuration options (lines 6 to 9):

1
2
3
4
5
6
7
8
9

conf.py:
  copyright: 2013-2015
  project: Sphinx Python Documentation Generator and Viewer
  version: 2.3
  release: 2.3.0
  intersphinx_mapping:
    restdoc:
    - https://docs.typo3.org/typo3cms/extensions/restdoc/
    - null

This will register prefix restdoc and let us link to any chapter of the documentation of extension Sphinx Documentation Viewer Plugin. For instance its ChangeLog with :ref:`ChangeLog for EXT:restdoc <restdoc:changelog>`. By convention, you should use the extension key (without underscore "_") as prefix for other manuals:

• ChangeLog for EXT:restdoc

Cross-link to TYPO3 source code¶

The trick described in chapter Advanced cross-links has been implemented for the TYPO3 source code API, making it possible and very easy to cross-link to the TYPO3 source code, either for a given class or even a given method.

To be able to cross-link to the TYPO3 API, you first need to add an Intersphinx mapping. To do so, open configuration file Settings.yml and add an Intersphinx mapping t3cmsapi:

1
2
3
4
5
6
7
8
9

conf.py:
  copyright: 2013-2015
  project: Sphinx Python Documentation Generator and Viewer
  version: 2.3
  release: 2.3.0
  intersphinx_mapping:
    t3cmsapi:
    - https://typo3.org/api/typo3cms/
    - null

In your documentation, you may then either link to a given class or a method:

See :ref:`t3cmsapi:TYPO3\\CMS\\Core\\Utility\\GeneralUtility` for
standard API methods.

You may send an email with
:ref:`t3cmsapi:TYPO3\\CMS\\Core\\Utility\\MailUtility::mail`.

which will be rendered as

See t3cmsapi:TYPO3\CMS\Core\Utility\GeneralUtility for standard API methods.

You may send an email with t3cmsapi:TYPO3\CMS\Core\Utility\MailUtility::mail.

A few additional anchors are created as well (available as :ref:`t3cmsapi:<anchor>`):

Let visitors edit manual on GitHub¶

In case your extension is hosted on GitHub, you may want to let visitors of https://docs.typo3.org edit the documentation of your extension by pressing a button "Edit me on GitHub":

This button is not shown by default. To make the button visible, you need to specify the relative URI of your GitHub project repository and the branch you want to use for documentation changes (typically "master") in the configuration file Documentation/Settings.yml in your repository:

1
2
3
4
5
6
7
8

conf.py:
  copyright: 2013-2015
  project: Sphinx Python Documentation Generator and Viewer
  version: 2.3
  release: 2.3.0
  html_theme_options:
    github_repository: xperseguers/t3ext-sphinx
    github_branch: master

where xperseguers/t3ext-sphinx is the relative URI in http://github.com/xperseguers/t3ext-sphinx.

The button will be visible the next time you publish your extension to TER.

Multilingual manual

In case you are providing a multilingual documentation as described above, the translation may of course be easily edited on GitHub as well.

For this to work, the configuration file Documentation/Localization.locale/Settings.yml should provide an additional option github_sphinx_locale:

1
2
3
4
5
6
7
8
9

conf.py:
  copyright: 2013-2015
  project: Générateur et visionneuse de documentation Sphinx Python
  version: 2.3
  release: 2.3.0
  html_theme_options:
    github_repository: xperseguers/t3ext-sphinx
    github_branch: master
    github_sphinx_locale: fr_FR