tut 0.1

UNKNOWN

Tut is a tool that helps you write tutorial style documentation using Sphinx.

Tutorial style documentation is documentation where sections build on one another, and include code examples along the way. Tut helps you manage the code in the tutorial as you write it, and include the correct segments in your document.

Tut makes it easy to manage tags in a git source repository, and include code from a specific tag (or branch or commit) in your Sphinx document using the built-in literalinclude directive. Tut consists of two pieces: a program to manage tags, and a Sphinx extension to switch tags during the Sphinx build.

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.

Restrictions

When Sphinx encounters a checkpoint directive, it performs a git checkout in target repository. This means that the repository should not contain uncommitted changes, to avoid errors on checkout.

Managing Tags

In addition to making it easy to switch between tags in your source repository, Tut provides a tool for managing those tags. The primary advantage of using Tut to manage your tags is that it provides support for rolling back history to make changes, and keeping subsequent tags intact.

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

$ tut init ./demosrc

If the path (./demosrc) is an existing git repository, Tut will install its post-rewrite hook. If it is not an existing repository, Tut will create the repository, install the hook, and add a first commit.

When you’ve made some changes and want to create a checkpoint, simple run tut checkpoint:

$ tut checkpoint step_one

You can optionally specify a commit message:

$ tut checkpoint step_one -m "The first checkpoint."

Under the hood, Tut is executing something like git commit -a.

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 roll back your repository to the step_one tag, and put you on a branch for editing. Once you’ve finished editing, commit the changes using tut checkpoint again:

$ tut checkpoint step_one -m "Edited Step One."

Tut will commit your changes, and then apply the future changes on top of them. The Tut post-rewrite hook will ensure that the tags (checkpoints) that come after step_one are updated to reflect their new SHAs.

News

0.1

Release date: 17 March 2013

• Support for switching to tags, branches, etc within Sphinx documents

• Initial implementation of wrapper script