DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Sphinx documentation viewer

This extension provides a backend module under section "Help":

Sphinx documentation viewer

A drop-down menu on top lists all loaded extensions that are featuring a Sphinx-based documentation and lets you quickly show it locally:

Selector to show an extension manual locally

Tip

The Sphinx documentation viewer automatically reloads the last manual you selected and if you choose the interactive layout, it will even bring you to the chapter you were reading.

Dashboard

If no documentation have been selected in the drop-down menu; that is, "Dashboard" is selected:

No documentation selected

a list of custom projects may be managed:

Manage custom projects

Then, depending on your environment, up to two additional tabs may be present. One that shows a list of locally-available extensions with an OpenOffice manual only. Action icons let you easily convert their manual to Sphinx using a standalone OpenOffice to Sphinx converter built-in this extension:

Easily convert OpenOffice manuals to Sphinx projects

Similarly, an empty Sphinx documentation project may be created for local extensions without any manual yet:

Kickstart a Sphinx documentation project

Layouts

Extension manuals may be rendered with different "layouts":

Internals

As Sphinx-based extension manuals are meant to be rendered on https://docs.typo3.org using the TYPO3 corporate design, they do not provide the general configuration files needed to be rendered locally.

When selecting an extension's manual to be shown from the drop-down menu the following process happens:

  • If a cached version of the main document is found, the viewer loads it right away and does not compile the documentation.

Otherwise:

  1. An empty Sphinx project is instantiated within typo3temp/tx_sphinx/extension-key and all files from EXT:extension-key/Documentation are copied in this directory
  2. The Sphinx project is built as HTML, JSON or PDF, according to selected layout
  3. HTML, JSON or PDF output is copied to typo3conf/documentation/extension-key/ language/format/ (language is always "default" for English, unless a multilingual documentation is found, just as this extension does for French)
  4. The viewer loads the main document (e.g., Index.html with HTML output)

Tip

A button on the right lets you force the extension's manual to be recompiled (thus recreating the cached version):

Button to force an extension manual to be rendered

Note

The Sphinx Documentation Viewer supports two types of extension's manual:

  1. Standard documentation layout with the a whole Sphinx project stored within EXT:extension-key/Documentation/, with the master document named Index.rst
  2. Simple reStructuredText README file as seen on Github or Bitbucket and saved as EXT:extension-key/README.rst

According to the selected layout, the main document is:

  • Static: Main document of HTML output is typo3conf/Documentation/extension-key/ default/html/Index.html
  • Interactive: Main document of JSON output is typo3conf/Documentation/extension-key/ default/json/Index.fjson
  • PDF: Main document of PDF output is typo3conf/Documentation/extension-key/ default/pdf/extension-key.pdf