{
    "info": {
        "author": "Nathan Yergler",
        "author_email": "nathan@yergler.net",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "=====\n Tut\n=====\n\n.. image:: https://travis-ci.org/nyergler/tut.svg?branch=master\n  :target: https://travis-ci.org/nyergler/tut\n\n.. image:: https://coveralls.io/repos/github/nyergler/tut/badge.svg?branch=master\n  :target: https://coveralls.io/github/nyergler/tut?branch=master\n\n\n**Tut** is a tool that helps you write technical documentation using Sphinx_ 1.6 and later.\n\n**Tut** provides a workflow that supports tutorial-style documents particularly well. If your writing includes code samples that build on one another, Tut is for you. **Tut** helps you manage the code in the tutorial as you write it, and include the correct segments in your document.\n\n**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** allows you to include code from a particular step in your Sphinx document. **Tut** also 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.\n\n**Tut** consists of two pieces: a program to manage branches, and a Sphinx\nextension to switch branches during the Sphinx build.\n\n\nUsing Tut\n=========\n\nI wrote **Tut** because I wanted an easier way to manage the sample code I was writing for `Effective Django`_. I was using ``git`` to 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.\n\n**Tut** is 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 hood **Tut** uses ``git``, so you can include your code as a sub-module and use the other git tools you've come to appreciate.\n\nTo start using **Tut**, run ``tut init <path>``::\n\n  $ tut init ./demosrc\n\nIf the path (``./demosrc``) is not an existing git repository, **Tut**\nwill initialize one and add an initial commit.\n\nSubsequent **Tut** commands should be run from within the **Tut**-managed\nrepository.\n\n::\n\n  $ cd demosrc\n\nTo start a point from your current position, run ``tut start``::\n\n  $ tut start step_one\n\nAfter you've created different points in your repository, you can run ``tut points`` to list them::\n\n  $ tut points\n  step_one\n  step_two\n\nIf you realize you've made a mistake and want to change the code at an\nearlier checkpoint, simply run ``tut edit``::\n\n  $ tut edit step_one\n\n**Tut** will check out the ``step_one`` branch, and you can make changes and commit them. Once you're done editing, commit your changes using ``git``. You'll also want to roll those changes forward, through the subsequent steps.\n\n::\n\n  $ tut next --merge\n\nRunning ``tut next`` will find the next step and check out that\nbranch. Adding ``--merge`` will also merge the previous step. If we're\ndone making changes to ``step_one``, running ``tut next --merge`` will\nmove us to ``step_two`` and merge ``step_one``.\n\nIncluding Code in Sphinx\n========================\n\nSphinx provides the literalinclude_ directive, which allows you to\ninclude source files, or parts of files, in your documentation. **Tut**\nallows you to switch to a specific git tag, branch, or commit before\nprocessing the inclusion.\n\nTo enable **Tut**, add ``tut.sphinx`` to the list of enabled extensions in\nyour Sphinx project's ``conf.py`` file::\n\n  extensions = [\n      # ...\n      'tut.sphinx',\n  ]\n\nThe ``checkpoint`` directive takes a single argument, which is the git\nreference to switch to. For example, the following directive will\ncheckout ``step_one`` (either a branch or tag) in the git repository\nin ``/src``::\n\n  .. tut:checkpoint:: step_one\n     :path: /src\n\nThe directive doesn't result in any output, but ``literalinclude`` (or\nother file-system inclusion directives) that come after the\n``checkpoint`` will use the newly checked-out version.\n\n**Tut** records the starting state of repositories the first time it\ndoes a checkout, and restores the initial state after the build completes.\n\nIf your document contains multiple checkpoints, you can specify the\npath once using the ``tut`` directive::\n\n  .. tut::\n     :path: /src\n\nNote that ``/src`` is evaluated using the same rules as govern\nliteralinclude_. That is, the file name is usually relative to the\ncurrent file\u2019s path. However, if it is absolute (starting with /), it\nis relative to the top source directory.\n\nWithin a checkpoint **Tut** provides two new directives for fetching content: ``tut:literalinclude`` and ``tut:diff``.\n\n``tut:literalinclude`` works a lot like Sphinx's built-in literalinclude_ directive. However, instead of loading the file from the filesystem directly, ``tut:literalinclude`` retrieves it from the git repository.\n\nFor example::\n\n  .. tut:checkpoint:: step_two\n     :path: /src\n\n     ...\n\n  .. tut:literalinclude:: setup.py\n\nWill fetch ``setup.py`` from the ``step_two`` branch in the git repository located at ``/src``.\n\n**Tut** can also show the changes between two checkpoints (branches) using the ``tut:diff`` directive. Like ``tut:literalinclude`` it uses the git repository referenced in the last checkpoint by default. You can specify the ``ref`` and ``prev_ref`` to compare; if omitted, ``ref`` defaults to the current checkpoint and ``prev_ref`` defaults to the previous point, as listed in the output of ``tut points``.\n\n::\n\n  .. tut:diff:: setup.py\n    :ref: step_two\n    :prev_ref: step_one\n    :path: /src/demosrc\n\n\nN.B.\n====\n\nWhen Sphinx encounters a ``checkpoint`` directive, it performs a ``git\ncheckout`` in target repository. This means that the repository should\nnot contain uncommitted changes, to avoid errors on checkout.\n\nNote that this will probably change soon, to allow for more flexible use of content from the git repository.\n\n\n.. _`Effective Django`: http://www.effectivedjango.com/\n.. _Sphinx: http://sphinx-doc.org/\n.. _branches: http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging\n.. _git: http://git-scm.org/\n.. _literalinclude: http://sphinx-doc.org/markup/code.html#directive-literalinclude\n\n\n\nNews\n====\n\nDEVELOPMENT\n\n(unreleased)\n\n...\n\n\n0.5.1\n--------\n\n*Release Date: 30 April 2017*\n\n* Fixed missing import which caused tut:literalinclude to silently fails\n\n0.5.0\n-----\n\n*Release Date: 30 April 2017*\n\n* Addition of ``tut:literalinclude`` and ``tut:diff`` directives\n* Sphinx directives are namespaced under ``tut:``\n* Drop support for Sphinx releases prior to 1.6\n* Drop support for Python 2\n* Use dedicated config file on special branch for maintaining point\n  list.\n* Added ``tut fetch`` to support retreiving all checkpoints.\n* Better error reporting when calling git fails.\n\n0.2\n---\n\n*Release date: 11 April 2013*\n\n* BACKWARDS INCOMPATIBLE\n* Removed post-rewrite hook, ``tut-remap``\n* Moved from tag-based checkpoints to branch-based\n* Added ``next`` sub-command to move from one step to the next\n* ``edit`` now checks out a branch\n\n0.1\n---\n\n*Release date: 17 March 2013*\n\n* Support for switching to tags, branches, etc within Sphinx documents\n* Initial implementation of wrapper script\n\n\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/nyergler/tut",
        "keywords": "",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "tut",
        "package_url": "https://pypi.org/project/tut/",
        "platform": "",
        "project_url": "https://pypi.org/project/tut/",
        "project_urls": {
            "Homepage": "http://github.com/nyergler/tut"
        },
        "release_url": "https://pypi.org/project/tut/0.5.1/",
        "requires_dist": [
            "Sphinx",
            "docopt",
            "pyyaml",
            "sh",
            "sphinxcontrib-websupport"
        ],
        "requires_python": "",
        "summary": "",
        "version": "0.5.1"
    },
    "last_serial": 2840848,
    "releases": {
        "0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "84dde81dc9fec14251305964b035c000",
                    "sha256": "398938b777ae254c8dcccb4230f0cb868cba68ef87cde08bad78309e4363ec88"
                },
                "downloads": -1,
                "filename": "tut-0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "84dde81dc9fec14251305964b035c000",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10887,
                "upload_time": "2013-03-18T02:59:14",
                "url": "https://files.pythonhosted.org/packages/f0/22/7602cdbbb5cd50f4e7ee1b1e908d664d712e337b79e33faf5a0dec937475/tut-0.1.tar.gz"
            }
        ],
        "0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5b15f21e4898359d29f1139199c3b36e",
                    "sha256": "3a39d50e29613d802b5667c1bde01a51c085fa886d509e69a0bf12f787e6e999"
                },
                "downloads": -1,
                "filename": "tut-0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "5b15f21e4898359d29f1139199c3b36e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10305,
                "upload_time": "2013-04-12T05:07:42",
                "url": "https://files.pythonhosted.org/packages/40/fd/49db1a7892e0f29526d5d4322bfff605820ccf9c6c6775b09c376ab44f16/tut-0.2.tar.gz"
            }
        ],
        "0.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "1c31e5d6707916bba74dd842d2beb7f3",
                    "sha256": "8130e6170c3df91de9e4924830b6f32b63c9f441ad3f8a2882cb2d536ce92024"
                },
                "downloads": -1,
                "filename": "tut-0.5-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "1c31e5d6707916bba74dd842d2beb7f3",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 22634,
                "upload_time": "2017-04-30T16:19:15",
                "url": "https://files.pythonhosted.org/packages/57/55/799a2146d43cf0779e492037e14339dee16d2d278e40a86331372db03090/tut-0.5-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "5d7bd022ee8cf516b830e4e6864b1577",
                    "sha256": "606944b4760aa15b71b7cb6a1e8dad5de97a0b29cfe18a05ee08838e29bea6b2"
                },
                "downloads": -1,
                "filename": "tut-0.5.tar.gz",
                "has_sig": false,
                "md5_digest": "5d7bd022ee8cf516b830e4e6864b1577",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18566,
                "upload_time": "2017-04-30T16:19:17",
                "url": "https://files.pythonhosted.org/packages/6f/9e/8da6c9ad153eacd93fde32538aaa533e4cdbe708cbc36c1d16ed3c93c084/tut-0.5.tar.gz"
            }
        ],
        "0.5.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0854266447170c3a9e97b5d3ffe5d516",
                    "sha256": "b73772a818a47f2f6439f5cff10235566fc91ee217bf592e5dc00865319a5892"
                },
                "downloads": -1,
                "filename": "tut-0.5.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "0854266447170c3a9e97b5d3ffe5d516",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 22906,
                "upload_time": "2017-04-30T20:07:16",
                "url": "https://files.pythonhosted.org/packages/85/b1/70291ea8313622c93448f2b9b4b2b8fefc7d9fa9bb70196915889fba0d3d/tut-0.5.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "4776d64b1f2501972bf534a8a68eaf2e",
                    "sha256": "defb1998bb54cfb0158cb3483ea867459aef7c9f14fc8b18176e6cb665f478a6"
                },
                "downloads": -1,
                "filename": "tut-0.5.1.tar.gz",
                "has_sig": false,
                "md5_digest": "4776d64b1f2501972bf534a8a68eaf2e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18796,
                "upload_time": "2017-04-30T20:07:18",
                "url": "https://files.pythonhosted.org/packages/61/15/6ef3ede12af12c71ef6191704a8b775090f2776744c8f77954782389ed02/tut-0.5.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0854266447170c3a9e97b5d3ffe5d516",
                "sha256": "b73772a818a47f2f6439f5cff10235566fc91ee217bf592e5dc00865319a5892"
            },
            "downloads": -1,
            "filename": "tut-0.5.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0854266447170c3a9e97b5d3ffe5d516",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 22906,
            "upload_time": "2017-04-30T20:07:16",
            "url": "https://files.pythonhosted.org/packages/85/b1/70291ea8313622c93448f2b9b4b2b8fefc7d9fa9bb70196915889fba0d3d/tut-0.5.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "4776d64b1f2501972bf534a8a68eaf2e",
                "sha256": "defb1998bb54cfb0158cb3483ea867459aef7c9f14fc8b18176e6cb665f478a6"
            },
            "downloads": -1,
            "filename": "tut-0.5.1.tar.gz",
            "has_sig": false,
            "md5_digest": "4776d64b1f2501972bf534a8a68eaf2e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 18796,
            "upload_time": "2017-04-30T20:07:18",
            "url": "https://files.pythonhosted.org/packages/61/15/6ef3ede12af12c71ef6191704a8b775090f2776744c8f77954782389ed02/tut-0.5.1.tar.gz"
        }
    ]
}