.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../Includes.txt


.. _customizing-rendering:

Customizing the rendering
^^^^^^^^^^^^^^^^^^^^^^^^^

In order to customize the output of documentation rendered as PDF with LaTeX to match the TYPO3 branding, we first
need to install the `Share corporate font family`_ and convert it to be compatible with LaTeX. Please refer to chapter
:ref:`installing-share-font` for instructions.

.. _`Share corporate font family`: https://typo3.org/about/the-brand/style-guide/the-typo3-font/


LaTeX template
""""""""""""""

The LaTeX template is defined in file :file:`conf.py`:

.. code-block:: python

	# Grouping the document tree into LaTeX files. List of tuples
	# (source start file, target name, title, author, documentclass [howto/manual]).
	latex_documents = [
	    ('Index', 'myext.tex', u'My Extension Documentation',
	     u'Xavier Perseguers', 'manual'),
	]

In this example, the document class within :file:`conf.py` is ``manual`` (last tupple of ``latex_documents``). This means
that after Sphinx has automatically added the prefix ``sphinx`` during compilation, the actual document class as seen by
LaTeX is ``sphinxmanual``:

.. code-block:: latex
	:linenos:

	% Generated by Sphinx.
	\def\sphinxdocclass{report}
	\documentclass[a4paper,10pt,english]{sphinxmanual}
	\usepackage[utf8]{inputenc}
	\DeclareUnicodeCharacter{00A0}{\nobreakspace}
	\usepackage{cmap}
	\usepackage[T1]{fontenc}
	\usepackage{babel}
	\usepackage{times}
	\usepackage[Bjarne]{fncychap}
	\usepackage{longtable}
	\usepackage{sphinx}
	\usepackage{multirow}

	\title{My Extension Documentation}
	\date{2013-06-30 22:25}
	\release{1.0.0}
	\author{Xavier Perseguers}

Sphinx provides two document classes:

- ``manual`` that is, ``sphinxmanual``, extending the real LaTeX document class ``report`` (by default two-side
  with full title page);

- ``howto`` that is, ``sphinxhowto``, extending the real LaTeX document class ``article`` (by default one-side).
  "howto" documents will not get appendices.  Also, howtos will have a simpler title page.


Both class files (:file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`) are copied to directory :file:`build/latex/`
during rendering.

After playing with the various options to customize the rendering, the outcome is that creating a custom document class
is not the best option as most of the settings are then overridden by package ``sphinx`` on line 12 in code above. This
package (file :file:`sphinx.sty`) is copied as well to directory :file:`build/latex/`.

LaTeX preamble
""""""""""""""

Additional commands may be added as preamble in the generated LaTeX file. This is easily done by editing file
:file:`conf.py`:

.. code-block:: python

	f = open('latex-styling.tex', 'r+');
	PREAMBLE = f.read();

	latex_elements = {
	    # The paper size ('letterpaper' or 'a4paper').
	    #'papersize': 'a4paper',

	    # The font size ('10pt', '11pt' or '12pt').
	    #'pointsize': '10pt',

	    # Additional stuff for the LaTeX preamble.
	    'preamble': PREAMBLE
	}

This will copy the contents of file :file:`latex-styling.tex` (in same directory as :file:`conf.py`) to the generated
LaTeX document. For instance, if :file:`latex-styling.tex` reads:

.. code-block:: latex

	% My personal "bold" command
	\newcommand{\mycommand}[1]{\textbf{#1}}

the generated LaTeX document becomes:

.. code-block:: latex

	% Generated by Sphinx.
	\def\sphinxdocclass{report}
	\documentclass[a4paper,10pt,english]{sphinxmanual}
	% snip (packages)
	% My personal "bold" command
	\newcommand{\mycommand}[1]{\textbf{#1}}

	\title{My Extension Documentation}
	\date{2013-06-30 22:25}
	\release{1.0.0}
	\author{Xavier Perseguers}

Other options
"""""""""""""

The configuration file :file:`conf.py` lets you further tune the rendering with LaTeX. Please consult
http://sphinx-doc.org/config.html#options-for-latex-output for further instructions.

TYPO3 template
""""""""""""""

We want to stick as much as possible to default rendering, to avoid having to change the LaTeX code generation from
Sphinx. As such, we choose to include a custom package ``typo3`` (file :file:`typo3.sty`) that will override some
settings of package ``sphinx``. To include it automatically, we simply use the ``preamble`` option of :file:`conf.py`:

.. code-block:: python

	latex_elements = {
	    # Additional stuff for the LaTeX preamble.
	    'preamble': '\\usepackage{typo3}'
	}

The package ``typo3`` is available from a dedicated repository, within directory :file:`latex.typo3/` and is
automatically copied to the build directory when using this extension. Alternatively, you may want to register it
globally within ``TEXMF`` if you plan to generate PDF from the command line solely.