Jan 26, 2015 Tags: Sphinx, T3Docs, Howto, Python
This post is about how to install the Sphinx documentation tools on your machine and how to get going with the first steps. Having done this you can render TYPO3 documentation projects at the commandline. For Linux, Mac and Windows. This post will be updated as needed.
Attention: I need your feedback: Martin Bless @ typo3.org
Updated on Aug 02, 2016
Navigate this page:
See also: TYPO3 documentation rendering
See also: About Sphinx
Requirements: You need Python 2.6 or better, 2.7 for this and Pip.
Run these commands to install everything:
sudo pip install --upgrade pip
sudo pip install --upgrade sphinx
sudo pip install --upgrade pyyaml
sudo pip install --upgrade t3SphinxThemeRtd
sudo pip install --upgrade t3fieldlisttable
sudo pip install --upgrade t3tablerows
sudo pip install --upgrade t3targets
sudo pip install --upgrade sphinxcontrib-googlechart
sudo pip install --upgrade sphinxcontrib-googlemaps
sudo pip install --upgrade sphinxcontrib-httpdomain
sudo pip install --upgrade sphinxcontrib-slide
sudo pip install --upgrade sphinxcontrib.youtube
# # nice to have:
# sudo pip install --upgrade pillow
# end.
Run these commands to install everything if sudo is not required:
pip install --upgrade pip
pip install --upgrade sphinx
pip install --upgrade pyyaml
pip install --upgrade t3SphinxThemeRtd
pip install --upgrade t3fieldlisttable
pip install --upgrade t3tablerows
pip install --upgrade t3targets
pip install --upgrade sphinxcontrib-googlechart
pip install --upgrade sphinxcontrib-googlemaps
pip install --upgrade sphinxcontrib-httpdomain
pip install --upgrade sphinxcontrib-slide
pip install --upgrade sphinxcontrib.youtube
# nice to have:
pip install --upgrade pillow
# end.
TYPO3 documentation follows this convention:
path/to/PROJECT
path/to/PROJECT/Documentation
path/to/PROJECT/Documentation/Index.rst
To render the documentation of such a project download this ‘_make’ folder to:
path/to/PROJECT/Documentation/_make
Afterwards you can directly render the documentation:
cd ./path/to/PROJECT/Documentation/_make
make html
make singlehtml
make
Open the result in the webbrowser:
firefox path/to/PROJECT/Documentation/_make/build/html/Index.html
firefox path/to/PROJECT/Documentation/_make/build/singlehtml/Index.html
Test for Python
Make sure Python 2 is available. | |
---|---|
Do this test: Type ‘python –version’ at the commandline: $ python --version
|
|
Example of success: $ python --version
Python 2.7.6
Good. Go to next step. |
Example of failure: $ python --version
Command not found
Bad. |
Read more. |
Test for PIP
Make sure the Python packet manager PIP is available. | |
---|---|
Run this test: Type ‘pip’ at the command line: $ pip
|
|
Example for success: $ pip
Usage:
pip <command> [options]
...
Usage information is being printed.
|
Example for failure: $ pip
Command not found
|
Good. Skip next step. |
Bad. Go to next step. |
Install PIP
Install the Python Packet Manager PIP |
---|
Do this:
|
Install general Python Packages
Install general Python packages | ||
---|---|---|
sphinx | The Sphinx documentation tools Run: $ sudo pip install --upgrade sphinx
Dependencies will be resolved and several other packages will be installed. Read more. |
mandatory |
yaml | Yaml support Run: $ sudo pip install --upgrade pyyaml
|
necessary for older TYPO3 projects that still
have a Settings.yml file instead of
Settings.cfg which is the standard nowadays |
pillow | Python imaging library Provide prerequisites: Run: $ sudo pip install --upgrade Pillow
Read more below and at ReadTheDocs. |
optional, nice to have |
Install the TYPO3 specific theme for Sphinx
Install the TYPO3 specific theme for Sphinx |
---|
Install latest version: $ pip install --upgrade t3SphinxThemeRtd
# or
$ sudo pip install --upgrade t3SphinxThemeRtd
Rerun this command whenever you suspect that updates are available. |
Install Sphinx extensions
Install Sphinx Extensions | ||
---|---|---|
t3fieldlisttable | Run: $ sudo pip install --upgrade t3fieldlisttable
Implements the ‘t3-field-list-table’ directive for Sphinx. The directive is commonly used in TYPO3 documentation. |
recommended, needed for TYPO3 projects |
t3tablerows | Run: $ sudo pip install --upgrade t3tablerows
Activates special rendering for some special definition list constructs in TYPO3 documentation. |
needed for TYPO3 projects |
t3targets | Run: $ sudo pip install --upgrade t3targets
Implements the ‘ref-targets-list’ directive for Sphinx. The directive inserts a list of all labels available for crossreferencing into the generated output of your documentation projects. |
recommended, needed for TYPO3 projects |
more ... | More contributed Sphinx extensions you may like. Run: pip install --upgrade sphinxcontrib-googlechart
pip install --upgrade sphinxcontrib-googlemaps
pip install --upgrade sphinxcontrib-httpdomain
#pip install --upgrade sphinxcontrib-numfig
pip install --upgrade sphinxcontrib-slide
pip install --upgrade sphinxcontrib.youtube
Install: # when sphinxcontrib.youtube wasn't up to date at PyPi:
git clone https://ithub.com/shomah4a/sphinxcontrib.youtube.git
cd sphinxcontrib.youtube
sudo python setup.py install
Search: pip search sphinxcontrib
pip search t3
|
optional |
A First Test Of TYPO3 rendering
Download a TYPO3 documentation project |
---|
Do this: Pick one that - as a service - has a Download: $ git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi
Go to the $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make
|
Build the HTML documentation: $ make html
List options:
$ make
Find the result in: $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make/build/html
Find logfiles and warnings in: $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make/_not_versioned
Watch the 'warnings.txt' file!
|
Run TYPO3 rendering locally
Render some ./Documentation project locally |
---|
Do this: Download the $ wget https://github.com/marble/typo3-docs-typo3-org-resources/archive/master.zip
Locate the $ cp -rp path/to/downloaded/_make ./Documentation/
|
The downloaded _make folder is generic and should run
out of the box. You don’t need to change anything. |
Build the HTML documentation: $ cd ./Documentation/_make
$ make html
$ make singlehtml
List options:
$ make
Find the results: $ firefox Documentation/make/build/html/Index.html &
$ firefox Documentation/make/build/singlehtml/Index.html &
Find logfiles and warnings in: $ cd ./Documentation/_make/_not_versioned
Watch the 'warnings.txt' file!
|
Provide metadata:
There is a Settings.cfg template as well in
the archive you downloaded from Github. So take
this file (Settings.cfg) and copy it to
./Documentation/ . Edit the file and provide the correct
metadata for your project. |
Pillow is the friendly PIL fork by Alex Clark and Contributors. PIL is the Python Imaging Library by Fredrik Lundh and Contributors. It is not required for Sphinx but may come in handy and it is nice to have.
Pillow is build from source, so the following libraries are required. Try this first to see whether it’s sufficient:
sudo apt-get install python-dev
sudo apt-get install libjpeg-dev
If not, install this as well:
sudo apt-get install libtiff5-dev libjpeg8-dev zlib1g-dev libfreetype6-dev \
liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python-tk
sudo pip install --upgrade Pillow
Fetch a precompiled binary from somewhere, for example:
This is the general Sphinx way to start a documentation project:
sphinx-quickstart
at the commandlineAdd these four lines at the end of conf.py
:
import t3SphinxThemeRtd
html_theme_path = []
html_theme_path.append(t3SphinxThemeRtd.get_html_theme_path())
html_theme = 't3SphinxThemeRtd'
Copy the folder a-starter-for-a-project-with-documentation
as PROJECT
Edit the meta data in PROJECT/Documentation/Settings.cfg
Start documenting in PROJECT/Documentation/Index.rst
To build the documentation locally:
cd PROJECT/Documentation/_make
make html
Note: This _make
folder is well suited to render ANY
standard documenation project with the new theme. A
standard documentation project has the files Documentation/Index.rst
and Documentation/Settings.cfg
and the folder
Documentation/_make
.
To view your documentation:
firefox PROJECT/Documentation/_make/build/html/Index.html
Tip: You can use a Watcher in PhpStorm or PyCharm to issue the
make html
command automatically.
Tip: Have a look at TemplatesForCopying/ExampleFiles as well.
The “_make” folder
of the starter project
is well suited to render ANY standard documenation project
with the new theme. A standard documentation project has the files
Documentation/Index.rst
and Documentation/Settings.cfg
and the folder Documentation/_make
.
You can use this Vagrant configuration to set up a Debian system with the Sphinx rendering tools. The ‘provision.sh’ bash file in there is very long - and that’s a deliberate choice as the intent is to provide a well readable recipe of what steps are necessary.
In that Vagrant box you can do LaTeX rendering to generate PDF files with Sphinx as well.
Michiel Roos contributed the TypoScript lexer!
Tip: Update!
Since 2016-02-02 and with this commit the TypoScript lexer has become part of the official Pygments distribution. So the following steps may not be necessary any more. Ccongratulations to us and Michiel, the hero with eternal fame :-)
To get the latest Pygments WITH builtin TypoScript support download the package and install it the traditional way:
$ cd path/to/downloaded/pygments
$ sudo python setup.py install
At the moment it has to be installed manually AFTER Sphinx is up and running. Sphinx pulls in the syntax highlighter Pygments. We need to add the TypoScript lexer to Pygments.
Depending on your system you may need admin rights (sudo) for this.
Find out, where the Python module Pygments is installed on your machine:
# run Python, import Pygments, print file location, exit
python -c "import pygments; print pygments.__file__"
# for example this line will be shown:
/usr/lib/python2.7/dist-packages/pygments/__init__.pyc
This means that in our case Pygments resides in
/usr/lib/python2.7/dist-packages/pygments/
.
Copy the TypoScript lexer typoscript.py
to /usr/lib/python2.7/dist-packages/pygments/lexers/
.
Change directory and go to the lexers/
folder:
cd /usr/lib/python2.7/dist-packages/pygments/lexers/
Update the mapping of known lexers. By running _mapping.py
it will create a new and updated version of itself:
cd /usr/lib/python2.7/dist-packages/pygments/lexers/
(sudo) python _mapping.py
Done!
Verify:
pygmentize -L
you should see typoscript somewhere in the list.
It may be necessary to repeat this procedure if new versions of Pygments are being installed.
(sphinx2015-10-21) mbless@srv123:
Add missing package:
# necessary for 'pip install pillow'
sudo apt-get install libjpeg-dev
Activate syntax highlighting for TypoScript:
ssh mbless@docs.typo3.org
cd
source ~/virtualenv/sphinx-2015-10-21/bin/activate
cd ~/virtualenv/sphinx2015-10-21/lib/python2.6/site-packages/pygments/lexers
wget https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py -O typoscript.py