Package: tut
Tutis a tool that helps you write technical documentation usingSphinx1.6 and later.Tutprovides a workflow that supports tutorial-style documents particularly well. If your writing includes code samples that build on one another, Tut is for you.Tuthelps you manage the code in the tutorial as you write it, and include the correct segments in your document.Tutmakes it easy to manage agitsource repository for your tutorial’s code by usingbranchesto record different steps. As you write the code for your tutorial,Tutallows you to include code from a particular step in your Sphinx document.Tutalso has basic support for showing the difference between two branches, allowing you to effectively show what’s changed in a way that’s readable for humans.Tutconsists of two pieces: a program to manage branches, and a Sphinx
extension to switch branches during the Sphinx build.Using TutI wroteTutbecause I wanted an easier way to manage the sample code I was writing forEffective Django. I was usinggitto track my changes to the text, but those changes weren’t the ones I was reflecting in the code: I could use git to tell me what changed in the text between two points in time, but I couldn’t easily tell what changed between chapters. The code, in effect, was a parallel set of changes, and I was interested in understanding them over the course of the text, not (necessarily) over the course of my writing timeline.Tutis a command-line tool that makes managing the code changes independently of the text changes more straight-forward. It allows you to define a set of “points” in the development of your source and switch back and forth between them. If you make a change to an early point in your code, you can roll that change forward so your future code is consistent. Under the hoodTutusesgit, so you can include your code as a sub-module and use the other git tools you’ve come to appreciate.To start usingTut, runtut init <path>:$ tut init ./demosrcIf the path (./demosrc) is not an existing git repository,Tutwill initialize one and add an initial commit.SubsequentTutcommands should be run from within theTut-managed
repository.$ cd demosrcTo start a point from your current position, runtut start:$ tut start step_oneAfter you’ve created different points in your repository, you can runtut pointsto list them:$ tut points
step_one
step_twoIf you realize you’ve made a mistake and want to change the code at an
earlier checkpoint, simply runtut edit:$ tut edit step_oneTutwill check out thestep_onebranch, and you can make changes and commit them. Once you’re done editing, commit your changes usinggit. You’ll also want to roll those changes forward, through the subsequent steps.$ tut next --mergeRunningtut nextwill find the next step and check out that
branch. Adding--mergewill also merge the previous step. If we’re
done making changes tostep_one, runningtut next--mergewill
move us tostep_twoand mergestep_one.Including Code in SphinxSphinx provides theliteralincludedirective, which allows you to
include source files, or parts of files, in your documentation.Tutallows you to switch to a specific git tag, branch, or commit before
processing the inclusion.To enableTut, addtut.sphinxto the list of enabled extensions in
your Sphinx project’sconf.pyfile:extensions = [
    # ...
    'tut.sphinx',
]Thecheckpointdirective takes a single argument, which is the git
reference to switch to. For example, the following directive will
checkoutstep_one(either a branch or tag) in the git repository
in/src:.. tut:checkpoint:: step_one
   :path: /srcThe directive doesn’t result in any output, butliteralinclude(or
other file-system inclusion directives) that come after thecheckpointwill use the newly checked-out version.Tutrecords the starting state of repositories the first time it
does a checkout, and restores the initial state after the build completes.If your document contains multiple checkpoints, you can specify the
path once using thetutdirective:.. tut::
   :path: /srcNote that/srcis evaluated using the same rules as governliteralinclude. 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.Within a checkpointTutprovides two new directives for fetching content:tut:literalincludeandtut:diff.tut:literalincludeworks a lot like Sphinx’s built-inliteralincludedirective. However, instead of loading the file from the filesystem directly,tut:literalincluderetrieves it from the git repository.For example:.. tut:checkpoint:: step_two
   :path: /src

   ...

.. tut:literalinclude:: setup.pyWill fetchsetup.pyfrom thestep_twobranch in the git repository located at/src.Tutcan also show the changes between two checkpoints (branches) using thetut:diffdirective. Liketut:literalincludeit uses the git repository referenced in the last checkpoint by default. You can specify therefandprev_refto compare; if omitted,refdefaults to the current checkpoint andprev_refdefaults to the previous point, as listed in the output oftut points... tut:diff:: setup.py
  :ref: step_two
  :prev_ref: step_one
  :path: /src/demosrcN.B.When Sphinx encounters acheckpointdirective, it performs agit checkoutin target repository. This means that the repository should
not contain uncommitted changes, to avoid errors on checkout.Note that this will probably change soon, to allow for more flexible use of content from the git repository.NewsDEVELOPMENT(unreleased)…0.5.1Release Date: 30 April 2017Fixed missing import which caused tut:literalinclude to silently fails0.5.0Release Date: 30 April 2017Addition oftut:literalincludeandtut:diffdirectivesSphinx directives are namespaced undertut:Drop support for Sphinx releases prior to 1.6Drop support for Python 2Use dedicated config file on special branch for maintaining point
list.Addedtut fetchto support retreiving all checkpoints.Better error reporting when calling git fails.0.2Release date: 11 April 2013BACKWARDS INCOMPATIBLERemoved post-rewrite hook,tut-remapMoved from tag-based checkpoints to branch-basedAddednextsub-command to move from one step to the nexteditnow checks out a branch0.1Release date: 17 March 2013Support for switching to tags, branches, etc within Sphinx documentsInitial implementation of wrapper script