Including Code Samples With rst2pdf

Every document I create these days is written in rst (ReStructuredText) and transformed into something useful using rst2pdf. This includes worksheets, reports, handouts and slide decks. Along the way I’ve learned a few tricks, and I try to write them down so I can look up how to do something. If this helps you too, then great :)

Start Simple

Include a code block in rst by adding something like this:

.. code-block:: php

Your code must then be indented, and the style persists until you “undent” again. There is pretty extensive language/syntax support since it is built on pygments, so you can use most language names instead of the php there.

Line Numbers and PHP Tags

In order to make the PHP syntax highlight work, your code must include a <?php tag. But this is very bad news if you only have 13 lines total to fit your example in! I usually start with something like this:

.. code-block:: php
:startinline: true
:linenos: true

This removes the need for the opening tag, and also adds line numbers to the code sample. This is especially helpful for presentations where the screen may be too far away for you to point at!

Including External Files

For some things, it’s neater to keep the code samples in separate files – I also like this approach since it keeps the code separate and I can run it and edit it, then just include it in my presentation.

.. code-block:: php
:linenos: true
:include: code/api/public/index.php

This brings in the named file, and also enables line numbers.

Including Sections From External Files

Currently I’m working on a presentation that pulls in smaller sections from an actual working codebase rather than having its own examples. rst can handle starting and stopping at specific points in the file.

The rst document looks like this:

.. code-block:: php
:startinline: true
:linenos: true
:linenos_offset: true
:include: code/api/public/index.php
:start-after: // start events list
:end-before: // end events list

Meanwhile, the PHP itself looks more like this:


// start setup
require "../vendor/autoload.php";
spl_autoload_register(function($classname) {
    include __DIR__ . "/../lib/" . $classname . ".php";

$app = new \Slim\Slim();

$container = new \Pimple\Container();
$container&#91;'db'&#93; = function ($c) {
    return new PDO("mysql:host=localhost;dbname=joindin", "joindin", "joindin");
$app->config('container', $container);
// end setup

// start view setup
$app->view(new View());
$app->response->headers->set("Content-Type", "application/json");
// end view setup

// start events list
$app->get('/events', function () use ($app) {
    $db = $app->config('container')['db'];
    $data = array();

    $model = new EventModel($db);
    $data['events'] = $model->getSomeEvents();

    $app->render("foo.php", array("mydata" => $data));
// end events list


With the comments in the code, I can use them as the start/stop mechanisms for my talks – very useful indeed!

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.