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.

Installing the extension

There are a few steps necessary to install the Sphinx Python Documentation Generator and Viewer extension. If you have installed other extensions in the past, you will run into little new here.

Note

MS Windows Users: Please set up your environment with Python first. Instructions are available as a separated chapter.

Installing the extension from Extension Manager

The Sphinx Python Documentation Generator and Viewer extension can be installed through the typical TYPO3 installation process using the Extension Manager.

Downloading and configuring Sphinx

In the Extension Manager, execute the update script this extension is providing:

Launching the update script within Extension Manager

Select a version of Sphinx you would like to use and start the import process with the "import" button:

Importing Sphinx to the local environment

Important

If the list of available versions of Sphinx is empty, you most probably lack OpenSSL support in PHP (this is a typical pitfall under MS Windows).

Everything should work out-of-the-box. Possible problems will be reported as Flash messages and a log of all operations is stored as typo3temp/tx_sphinx/IMPORT-date.log. The general process of importing Sphinx is as follows:

  1. Fetch the version as a zip archive from https://github.com/sphinx-doc/sphinx/releases into directory typo3temp/
  2. Unpack the zip archive into directory uploads/tx_sphinx/version/
  3. Build the Python libraries into directory typo3temp/tx_sphinx/sphinx-doc/version/
  4. [Not on MS Windows, other OS : if activated] Install Python Imaging Library (https://pypi.python.org/pypi/PIL), needed for supporting common image types with rst2pdf
  5. [Not on MS Windows, other OS : if activated] Install rst2pdf (http://rst2pdf.ralsina.me/), as a simple way of building PDF
  6. Fetch 3rd-party plugins for Sphinx: https://bitbucket.org/birkenfeld/sphinx-contrib/
  7. Install PyYAML library (http://pyyaml.org/wiki/PyYAML), needed for building TYPO3 documentation
  8. Install Pygments library (http://pygments.org/), and configure TypoScript highlighting
  9. Install TYPO3-related commands provided by the TYPO3 Documentation Team

The manual process buttons let you locally change files and rebuild your environment. This is particularly useful if you want to use the Git repositories of the TYPO3-related commands instead of a snapshot. Please note however that the repositories will be automatically used if your system supports the git command.

The "download" button fetches the corresponding sources of Sphinx, the TYPO3-related commands, the PyYAML library, the Pygments library, ... if they are not available locally.

Important

It is known that the Python Imaging Library and/or rst2pdf might fail to be successfully installed and configured on some systems. However, as these libraries are only used to render PDF with rst2pdf and as the recommended method for rendering PDF is to use LaTeX anyway, you should not worry if you are unable to install rst2pdf locally.

Tip

If the command git is detected on your system, the Git repository will be cloned instead of fetching once for all the TYPO3-related commands. However, if it fails, or if git is not detected, it will fetch a snapshot instead. In such case, you may prefer to clone the official Git repository manually.

To do so, open a terminal and run:

$ cd /path/to/uploads/tx_sphinx/
$ rm -rf t3SphinxThemeRtd sphinxcontrib.t3fieldlisttable \
    sphinxcontrib.t3tablerows sphinxcontrib.t3targets
$ git clone https://github.com/TYPO3-Documentation/t3SphinxThemeRtd.git
$ git clone https://github.com/TYPO3-Documentation/sphinxcontrib.t3fieldlisttable.git
$ git clone https://github.com/TYPO3-Documentation/sphinxcontrib.t3tablerows.git
$ git clone https://github.com/TYPO3-Documentation/sphinxcontrib.t3targets.git

The "build" button builds or rebuilds the corresponding version of the Sphinx environment with the TYPO3-related commands, PyYAML, Pygments, Python Imaging Library and rst2pdf. Good to know: TypoScript support for Pygments is automatically updated, if needed, upon rebuilding your Sphinx environment.

Finally, the "remove" button removes both the sources and the corresponding version of the Sphinx environment.

Important

This button WILL NOT remove sources of the TYPO3-related commands, the PyYAML library, Pygments, the Python Imaging Library or rst2pdf.

Choosing the version of Sphinx

In the Extension Manager, configure this extension as usual:

Configuring the extension within Extension Manager

The first tab "basic" lets you choose which version of Sphinx should be used to render your documents:

Configuring the version of Sphinx to be used by default

Choosing how to render PDF

The second tab "pdf" lets you choose which PDF builder you prefer (either rst2pdf or LaTeX) and whether you want to install and configure rst2pdf:

Configuring how to render PDF

Tip

Except for MS Windows users, rst2pdf is available by default with this extension. However, if you want better output, you should consider using LaTeX instead. Please read chapter Rendering PDF from reStructuredText for instructions.

Choosing the 3rd-party plugins to install

The third tab "plugins" lets you activate additional Sphinx extensions. Some of them are available on docs.typo3.org, and are as such suited for use with your extension manuals:

Configuring the 3rd-party plugins to install

Please read chapter 3rd-party plugins for instructions on how to use them in your documents.

Important

Make sure to rebuild your Sphinx environment after activating new plugins.

Speed-up rendering

The fourth tab "advanced" lets you tweak advanced settings to speed-up the rendering.

Advanced settings