tut 0.2

Including Code in Sphinx

Sphinx provides the literalinclude directive, which allows you to include source files, or parts of files, in your documentation. Tut allows you to switch to a specific git tag, branch, or commit before processing the inclusion.

To enable Tut, add tut.sphinx to the list of enabled extensions in your Sphinx project’s conf.py file:

extensions = [
    # ...
    'tut.sphinx',
]

The checkpoint directive takes a single argument, which is the git reference to switch to. For example, the following directive will checkout step_one (either a branch or tag) in the git repository in /src:

.. checkpoint:: step_one
   :path: /src

The directive doesn’t result in any output, but literalinclude (or other file-system inclusion directives) that come after the checkpoint will use the newly checked-out version.

If your document contains multiple checkpoints, you can specify the path once using the tut directive:

.. tut::
   :path: /src

Note that /src is evaluated using the same rules as govern literalinclude. That is, the file name is usually relative to the current file’s path. However, if it is absolute (starting with /), it is relative to the top source directory.

Tut records the starting state of repositories the first time it does a checkout, and restores the initial state after the build completes.

Managing Branches

In addition to making it easy to switch between branches or tags in your source, Tut provides a tool for managing branches in the repository. Tutorials usually have “steps” – discreet units that build upon previous ones – and Tut models those as branches[1]. Each step’s branch forks from the previous step’s branch. Note that use of the Tut command line tool is completely optional: Tut works great with Sphinx and git on their own.

To start using Tut, run tut init <path>:

$ tut init ./demosrc

If the path (./demosrc) is not an existing git repository, Tut will initialize one and add an initial commit.

When you want to start a new step (checkpoint) starting from the one you’re currently on, run tut start:

$ tut start step_one

After you’ve made checkpoints in your repository, you can run tut points to list the checkpoints:

$ tut points
step_one
step_two

If you realize you’ve made a mistake and want to change the code at an earlier checkpoint, simply run tut edit:

$ tut edit step_one

Tut will check out the step_one branch, and you can make changes and commit them. Once you’re done editing, you’ll want to roll those changes forward, through the subsequent steps.

$ tut next --merge

Running tut next will find the next step and check out that branch. Adding --merge will also merge the previous step. If we’re done making changes to step_one, running tut next --merge will move us to step_two and merge step_one.

News