Rendering reST on Linux
- 1 Requirements
- 2 Installing the Components
- 3 First Project with Sphinx
- 4 Troubleshooting
- Python: used by Sphinx
- Sphinx: main tool used to transform reST (.rst) into HTML or PDF
- TYPO3 templates: official TYPO3 templates for reST
notice - Note
- LaTeX: document preparation system used as intermediate format by Sphinx to generate prettier PDF out of reST files
notice - Note
Installing the Components
Python should already be installed. To check this, open a console/terminal and type
You should see something like
Python 2.6.8 (unknown, Apr 19 2012, 01:24:00) [GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>>
Then quit as usual with ^D (ctrl+D).
The setup for the TYPO3 documentation requires the use of YAML. Thus you need to install the Python YAML module. To check installed module:
$ python >>> help('modules')
The simplest way to install that module is to use "easy_install". On Debian, easy_install is provided by package 'python-pip'
$ (sudo) easy_install pyyaml
Hereafter we describe the process to install Sphinx as a stable version or from a development snapshot.
Sphinx may be available in the ports of your system. Best is to check this first.
MacOS X with MacPorts:
$ sudo port install py-sphinx $ sudo port select sphinx py27-sphinx
At the time of writing, installing Sphinx with:
$ sudo apt-get install python-sphinx
provides an old version of Sphinx (0.6.x) that does not support gettext (JSON) extraction. So we suggest you install it with:
$ sudo apt-get install python-setuptools $ easy_install -U Sphinx
If your operating system does not provide such packages or typically if you are using MacOS without MacPorts, you may install Sphinx from the Python Package Index with:
$ easy_install -U Sphinx
$ sudo urpmi python-sphinx
DISCLAIMER: You really should consider using an official stable distribution unless you know that you need the bleeding edge version of Sphinx.
You can download a snapshot from the Mercurial development repository:
Alternatively, you may clone the development repository with:
$ hg clone https://bitbucket.org/birkenfeld/sphinx
Then compile and install:
$ python setup.py build $ sudo python setup.py install
Installing the TypoScript lexer
Syntax highlighting is performed using Pygments. A dedicated TypoScript lexer exists and is used to perform syntax highlighting on TS blocks in the documentation.
To install the lexer, do the following:
1) get the lexer from: https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py and copy it to wherever the Pygments lexer are located on your machine.
$ wget https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py
2) move to that directory and update the list of available lexers by running:
$ (sudo) python _mapping.py
Note: on Mac OS X, the lexers are found in "/Library/Python/(version number)/site-packages/Pygments-(some other version number).egg/pygments/lexers/"
Note: on Mageia Linux the lexers are found in "/usr/lib/python(version number)/site-packages/pygments/lexers/"
Installing TYPO3 Templates
The TYPO3 templates are available for the time being from a dedicated Git repository. If you did not yet configure your environment for using Git, please do so using one of the Git Tutorials.
The template projects is available from git://git.typo3.org/Documentation/RestTools.git. Clone that repository and move into it:
$ git clone git://git.typo3.org/Documentation/RestTools.git $ cd RestTools
Move down one more sub-folder and run the provided installer:
$ cd ./ExtendingSphinxForTYPO3 $ (sudo) python setup.py install
This installs the TYPO3 Sphinx theme on your machine. Next time you will compile your documentation with
$ make html
you will have a nicer HTML documentation using the official TYPO3 template.
First Project with Sphinx
Please read our dedicated tutorial.
The setup may not go as smoothly as described above. Here are some tips that will hopefully be useful.
Mac OS X and MacPorts: conflicting Python installs
(Francois (talk) 21:03, 5 July 2012 (CEST)) I encountered problems when trying to install Sphinx via MacPorts. MacPorts installed Python too, because it was a dependency of Sphinx, so you end up with several versions of Python installed (since OS X ships with one already). Running "sphinx-build" obviously called the "python" interpreter from OS X and not from MacPorts causing errors like:
sphinx-build -b html -d build/doctrees -c . -a -E -w ./_not_versioned/warnings.txt .. build/html Traceback (most recent call last): File "/opt/local/bin/sphinx-build", line 5, in ? from pkg_resources import load_entry_point File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 2735, in ? working_set.require(__requires__) File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 690, in require needed = self.resolve(parse_requirements(requirements)) File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 588, in resolve raise DistributionNotFound(req) pkg_resources.DistributionNotFound: uuid>=1.30 make: *** [html] Error 1
Installing Sphinx using "easy_install" instead solved this issue.
Missing default locale
On some systems (the problem is reported in particular on Mac OS X Lion and Ubuntu), Python will complain about an invalid locale. The error trace ends with something like:
File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 496, in getdefaultlocale return _parse_localename(localename) File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 428, in _parse_localename raise ValueError, 'unknown locale: %s' % localename ValueError: unknown locale: UTF-8 make: *** [html] Error 1
In such a case, it is necessary to define the default locale by using:
export LANG="en_US.UTF-8" export LC_ALL="en_US.UTF-8"
The exact syntax will depend on the shell you use. You should set these command in your profile to avoid having to type them every time.