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":
A drop-down menu on top lists all loaded extensions that are featuring a Sphinx-based documentation and lets you quickly show it 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:
a list of custom projects may be managed:
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:
Similarly, an empty Sphinx documentation project may be created for local extensions without any manual yet:
Layouts¶
Extension manuals may be rendered with different "layouts":
Static: This renders and shows the HTML version;
Interactive: This renders and shows the JSON version and as such requires extension :ter:`Sphinx Documentation Viewer Plugin (restdoc) <restdoc>`. In addition, this layout features an integrated reStructuredText editor to let you quickly edit and recompile a given chapter;
PDF: This renders and shows the PDF version and as such requires either pdflatex or rst2pdf:
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:
- An empty Sphinx project is instantiated within
typo3temp/tx_sphinx/extension-key
and all files fromEXT:extension-key/Documentation
are copied in this directory - The Sphinx project is built as HTML, JSON or PDF, according to selected layout
- 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) - 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):
Note
The Sphinx Documentation Viewer supports two types of extension's manual:
- Standard documentation layout with the a whole Sphinx project stored within
EXT:extension-key/Documentation/
, with the master document namedIndex.rst
- 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