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:
Select a version of Sphinx you would like to use and start the import process with the "import" button:
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:
- Fetch the version as a zip archive from https://github.com/sphinx-doc/sphinx/releases into
directory
typo3temp/
- Unpack the zip archive into directory
uploads/tx_sphinx/version/
- Build the Python libraries into directory
typo3temp/tx_sphinx/sphinx-doc/version/
- [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
- [Not on MS Windows, other OS : if activated] Install rst2pdf (http://rst2pdf.ralsina.me/), as a simple way of building PDF
- Fetch 3rd-party plugins for Sphinx: https://bitbucket.org/birkenfeld/sphinx-contrib/
- Install PyYAML library (http://pyyaml.org/wiki/PyYAML), needed for building TYPO3 documentation
- Install Pygments library (http://pygments.org/), and configure TypoScript highlighting
- 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:
The first tab "basic" lets you choose which version of Sphinx should be used to render your documents:
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:
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:
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.