Templating, Custom Roles, and Custom Classes

If you want to customize some of the output, you can make a custom template file. You can make custom formatting for roles and classes real fast by overriding \DUroleNAME and DUCLASSNAME (as an environment) for a role or class with name NAME respectively. A minimal example of this might be something like this:

$head_prefix% generated by Docutils <http://docutils.sourceforge.net/>
% rubber: set program xelatex
\usepackage[margin=20mm]{geometry}

\usepackage{multicol}
\newenvironment{DUCLASScontact}{\begin{multicols}{3}}{\end{multicols}}

% \defaultfontfeatures{Scale=MatchLowercase}
% straight double quotes (defined T1 but missing in TU):
\ifdefined \UnicodeEncodingName
  \DeclareTextCommand{\textquotedbl}{\UnicodeEncodingName}{%
    {\addfontfeatures{RawFeature=-tlig,Mapping=}\char34}}%
\fi
$requirements
%%% Custom LaTeX preamble
$latex_preamble

%%% User specified packages and stylesheets

$stylesheet
%%% Fallback definitions for Docutils-specific commands
$fallbacks$pdfsetup
$titledata

%%% Body
\begin{document}
$body_pre_docinfo$docinfo$dedication$abstract$body
\end{document}

Put this in a file, and add --template=xelatex.tex (or whatever you named the file) to your rst2xetex command.

Making Admonitions Look Better (and work with verbatim!)

Admonitions are implemented as LaTeX commands, not environments. As a side effect of this, verbatim environments will not work within admonitions [1]. Of course, there exists a pretty way to solve this problem (subclassing the XeLaTeX writer to write enviornments instead). But this is not a page about pretty solutions, but rather hacks. So we will implement it using a pretty ugly hack.

First, we're going to need something that supports libpcre. Python's re won't do, we're going to need recursive regular expressions. And Perl's implementation of recursive expressions is kinda borked. As it turns out, PHP uses libpcre and was installed on my system, so that's going to be my weapon of choice [2]:

<?php
$re = '/\\\\DUadmonition\[([^\]-]*)(?:-[^\]]*)?\]\{\n\\\\DUtitle\[\1(?:-[^\]]*)?\]\{([^}]*)\}\n((?:[^{}]++|\{(?3)\})*)\}/smx';
$data = stream_get_contents(STDIN);
while (preg_match($re, $data)) {
    $data = preg_replace($re, '\\\\begin{\1box}{\2}' . "\n" . '\3' . "\n" . '\\\\end{\1box}', $data);
}
echo $data;
?>

Next, implement environments for each kind of NAMEbox you are using. I used tcolorbox, as it looks pretty great and also makes this pretty easy.

\usepackage{tcolorbox}
\newtcolorbox{systembox}[1]{colback=red,colframe=red!50!black,coltitle=white,coltext=white,fonttitle=\bfseries,title=#1}
\newtcolorbox{importantbox}[1]{colback=orange!20!white,colframe=orange,fonttitle=\bfseries,title=#1}
\newtcolorbox{notebox}[1]{colback=yellow!50!white,colframe=yellow!50!black,fonttitle=\bfseries,title=#1}
\newtcolorbox{warningbox}[1]{colback=red!15!white,colframe=red,coltitle=white,fonttitle=\bfseries,title=#1}
\newtcolorbox{admonitionbox}[1]{colback=blue!10!white,colframe=blue,fonttitle=\bfseries,title=#1}

You may have to implement a few more than that, depending on your needs.

That's all. Just pipe the output of rst2xetex into your PHP script and you should be good to go. Don't let any software engineers see your code.

No Support for Custom Document Classes

rst2beamer hardcodes the document class to beamer, even though you may want to use your own document class that derives from beamer. If this is the case, implement everything you would have in your document class in a file called beamerthemeNAME.sty and set --theme=NAME when you call rst2beamer. This should give you near equivalent functionality.

Compiling Beamer Things as HTML, LaTeX, etc

To a certain extent, rst2beamer provides you with equivalent container directives to its own beamer-* directives. Use these where you can.

But, you may need to make use of the beamer-columnset and beamer-column directives, which have no container equivalent. In this case, simply patch these up to be containers in things that are not rst2beamer (e.g., Sphinx):

import docutils.parsers.rst as rst
import docutils.parsers.rst.directives.body as body

class LooseContainer(body.Container):
    option_spec = {'name': str, 'width': str}
    def __init__(self, *args, width=None, **kwargs):
        super().__init__(*args, **kwargs)
rst.directives.register_directive('beamer-column', LooseContainer)
rst.directives.register_directive('beamer-columnset', LooseContainer)

Pause, and the like

You could just use a raw directive:

.. raw:: latex

    \pause

But I might reccomend making this a substitution to make it a bit easier:

.. |pause| raw:: latex

    \pause

Hiding the relbar

If you are not using Sphinx for documentation, the relbar might not be of any use for you. For the classic theme, you can disable it by overriding it in _templates/layout.html:

{% extends "!layout.html" %}
{% block relbar1 %}{% endblock %}
{% block relbar2 %}{% endblock %}

External Links in New Tabs

If you want external links to open in new tabs, add to your conf.py:

from sphinx.writers.html import HTMLTranslator
class PatchedHTMLTranslator(HTMLTranslator):
    def visit_reference(self, node):
        if node.get('newtab') or not (node.get('target') or node.get('internal') or 'refuri' not in node):
            node['target'] = '_blank'
        super().visit_reference(node)

def setup(app):
    app.set_translator('html', PatchedHTMLTranslator)

This also gives you the ability to use the newtab parameter to a reference, have it show as internal, but open in a new tab. I use this for linking to slide PDFs.