skip to navigation
skip to content

tut 0.2

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 a git source repository for your tutorial’s code by using branches to record different steps. As you write the code for your tutorial, Tut lets you include code from a particular branch (or tag or commit) in your Sphinx document using the built-in literalinclude directive.

Tut consists of two pieces: a program to manage branches, and a Sphinx extension to switch branches 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 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.

[1]Tut 0.1 modeled these as tags, but after some experience with managing third party contributions, branches appear to be more flexible and useful.

News

0.2

Release date: 11 April 2013

  • BACKWARDS INCOMPATIBLE
  • Removed post-rewrite hook, tut-remap
  • Moved from tag-based checkpoints to branch-based
  • Added next sub-command to move from one step to the next
  • edit now checks out a branch

0.1

Release date: 17 March 2013

  • Support for switching to tags, branches, etc within Sphinx documents
  • Initial implementation of wrapper script
 
File Type Py Version Uploaded on Size
tut-0.2.tar.gz (md5) Source 2013-04-12 10KB