TikZ extension for Sphinx
pip install sphinxcontrib-tikz==0.4.19
This extension to Sphinx enables the use of the PGF/TikZ LaTeX package to draw nice pictures. (See CTAN or sourceforge; the manual is, e.g., here. Also have a look at contributions such as pgfplots.)
Use the extension at your own risk. Anything might change in future versions without further notice.
Version: | 0.4.6 |
---|---|
Author: | Christoph Reller christoph.reller@gmail.com
|
License: | BSD License |
Git Repository: | https://bitbucket.org/philexander/tikz |
PyPI Package: | http://pypi.python.org/pypi/sphinxcontrib-tikz |
Documentation: | http://sphinxcontrib-tikz.readthedocs.io |
This extension relies on two software packages being installed on your computer:
latex
with the tikz
and the amsmath
packagespdf2svg
pdftoppm
(part of the Poppler pdf library) and pnmtopng
(part of the Netpbm package)pdftoppm
(part of the Poppler pdf library) and
convert
(part of the ImageMagick package)ghostscript
For Ubuntu Linux you roughly have to make sure that the following packages are installed:
texlive
and texlive-pictures
(and maybe more LaTeX packages)pdf2svg
poppler-utils
and netpbm
poppler-utils
and imagemagick
ghostscript
For Mac OS X a possible way of getting this extension working is as follows:
tikz
package.For Windows do the following:
Install the MiKTeX LaTeX distribution and include
the tikz
package when installing.
Depending on the chosen conversion suite, you have to install the following:
pdf2svg suite:
Get the Windows binaries from GitHub copy all the files to some
directory and add this directory to the PATH
environment variable.
Netpbm suite:
If you don't want to install the full packages above, you can copy the
following files to some directory and add this directory to the PATH
environment variable:
From Xpdf:
pdftoppm
From NetPbm:
pnmtopng.exe
libnetpbm10.dll
libpng13.dll
rgb.txt
Also, you need to create a new environment variable
RGBDEF=C:\TikzSphinx\rgb.txt
assuming you copy the files to the
C:\TikzSphinx
directory.
ImageMagick suite:
Install the Xpdf package (same as for the Netpbm suite) and install ImageMagick from here.
GhostScript suite:
Get the GhostScript binary from here, copy it to some
directory and add this directory to the PATH
environment variable.
If you have installed the Tikz Sphinx extension e.g. using PyPI, then you have to load the
extension in the Sphinx project configuration file conf.py
by:
extensions = ['sphinxcontrib.tikz']
Additionally, the following configuration values are supported:
Choose the image processing ‹suite›
, either 'pdf2svg'
, 'Netpbm'
,
'ImageMagick'
, 'GhostScript'
('pdf2svg'
by default):
tikz_proc_suite = ‹suite›
Note
GhostScript
.'pdf2svg'
which produces svg.Enable/disable transparent graphics (enabled by default):
tikz_transparent = ‹True or False›
Add ‹string›
to the LaTeX preamble used for building the TikZ
picture:
tikz_latex_preamble = ‹string›
Add \usetikzlibrary{‹string›}
to the LaTeX preamble used for building the
TikZ picture:
tikz_tikzlibraries = ‹string›
Note
If you want to use the latex
target, then you have to take care to
include in tikz_libraries
any ‹tikz libraries›
given to the libs
option of the tikz
directive (see :ref:`usage`)
Note
If you want to make use of the TikZ externalization library for the LaTeX build output, then you may want to change the line:
LATEXOPTS =
in Sphinx LaTeX Makefile (/usr/share/sphinx/texinputs/Makefile
) to:
LATEXOPTS = "-shell-escape"
The extension adds a tikz
-directive and a tikz
-role.
The tikz-directive can be used in two ways:
.. tikz:: ‹tikz code, potentially broken
across lines›
:libs: ‹tikz libraries›
:stringsubst:
or:
.. tikz:: ‹caption, potentially broken
across lines›
:libs: ‹tikz libraries›
:stringsubst:
‹tikz code, potentially broken
across lines›
The ‹caption›
is optional, but if present it is printed as a picture caption
below the picture.
The :libs:
option expects its argument ‹tikz libraries›
to be a comma
separated list of Tikz libraries to use. If you want to build the LaTeX
target then make sure to add these libraries to the configuration value
tikz_tikzlibraries
in conf.py
.
The :stringsubst:
option enables the following string substitution in the
‹tikz code›
: Before processing the ‹tikz code›
the string $wd
or
$(wd)
is replaced by the project root directory. This is convenient when
referring to some source file in the LaTeX code.
The ‹tikz code›
is code according to the TikZ LaTeX package. It
behaves as if inside a tikzpicture
environment. The presence of
\begin{tikzpicture}
and \end{tikzpicture}
is optional.
Alternatively to providing the ‹tikz code›
, the :include:
option can be
used to import the code from a file:
.. tikz::‹caption, potentially broken
across lines›
:libs: ‹tikz libraries›
:include: ‹filename›
:stringsubst:
The tikz-role is used as follows:
:tikz:`‹tikz code›`
The ‹tikz code›
is code according to the Tikz LaTeX package. It
behaves as if inside a \tikz
macro.
Note
These examples only render in a Sphinx project with a proper configuration of the Tikz Sphinx extension.
.. tikz:: [>=latex',dotted,thick] \draw[->] (0,0) -- (1,1) -- (1,0)
-- (2,0);
:libs: arrows
.. tikz:: [>=latex',dotted,thick] \draw[->] (0,0) -- (1,1) -- (1,0)
-- (2,0);
:libs: arrows
.. tikz:: An Example Directive with Caption
\draw[thick,rounded corners=8pt]
(0,0)--(0,2)--(1,3.25)--(2,2)--(2,0)--(0,2)--(2,2)--(0,0)--(2,0);
.. tikz:: An Example Directive with Caption
\draw[thick,rounded corners=8pt]
(0,0)--(0,2)--(1,3.25)--(2,2)--(2,0)--(0,2)--(2,2)--(0,0)--(2,0);
An example role :tikz:`[thick] \node[blue,draw] (a) {A};
\node[draw,dotted,right of=a] {B} edge[<-] (a);`
An example role :tikz:`[blue,thick] \node[draw] (a) {A}; \node[draw,dotted,right of=a] {B} edge[<-] (a);`
Example of a Tikz picture included from a file:
.. tikz::
:include: example.tikz
If you use the tikz
directive inside of a table or a sidebar and you specify
a caption then the LaTeX target built by the sphinx builder will not compile.
This is because, as soon as you specify a caption, the tikzpicture
environment is set inside a figure
environment and hence it is a float and
cannot live inside a table or another float.
If you enable :stringsubst:
and you happen to have any LaTeX math expression
starting with wd
(i.e., you would like to write $wd ...
then you must
insert some white space, e.g., $w d ...
to prevent string substitution.