Metadata-Version: 1.0
Name: tut
Version: 0.2
Summary: UNKNOWN
Home-page: http://github.com/nyergler/tut
Author: Nathan Yergler
Author-email: nathan@yergler.net
License: BSD
Description: =====
         Tut
        =====
        
        **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.
        
        .. _Sphinx: http://sphinx-doc.org/
        .. _branches: http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging
        .. _git: http://git-scm.org/
        .. _literalinclude: http://sphinx-doc.org/markup/code.html#directive-literalinclude
        
        
        
        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
        
Platform: UNKNOWN
