-.. Sphinx PatchQueue documentation master file, created by
- sphinx-quickstart on Mon Feb 4 15:21:35 2013.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
Welcome to Sphinx PatchQueue's documentation!
+Sphinx-PatchQueue is a dedicated to making tutorial-type document,
+where the reader is walked through the evolution of a file or group of
+files, simpler to author and to consume.
+Its core idea is that the evolution of the file or group of files can
+be captured by a patch queue, as provided by Quilt_ or `Mercurial
+Queues`_. Holding the progress of the example code in a formal,
+versioned structure independent from (but possibly contained within)
+the versioning of the document/tutorial itself makes it easier to
+embed and maintain said example code in a structured manner: the
+evolution shown to the reader is captured in the patch queue, while
+the evolution of the tutorial itself and the patch queue(s) within it
+(such as typos at various steps of the example) is captured by the
+wider versioning of the document.
+.. queue:: patches/series
+After having added sphinx-patchqueue to your extensions_, two new
+directives become available. The first one, :rst:dir:`queue`, is used
+to configure the patch queue for the current document. It simply takes
+the (relative) path to a "series" file (file listing the queue's patch
+Displaying patch sequences
+The second directive is :rst:dir:`patch`. It advances to the next
+patch of the current queue (the first patch if it follows a
+:rst:dir:`queue`) and displays the patch content as a code block,
+filtered if necessary to only show the lines affected by the patch
+By default, patches are displayed as applied (to the file they
+affected), only the "diff context" is displayed and the lines altered
+(added, since the removed ones are not visible after application) are
+emphasized; but each patch allows toggling its view to either a "patch
+view" (displays a unified diff view of the patch) or a "full view" of
+the file after application.
+.. rst:directive:: .. queue:: path
+ Adds the patch queue whose series file is ``path`` to the current
+ document's environment, before the application of any patch.
+ :rst:dir:`queue` has no output.
+.. rst:directive:: patch
+ Advances to the next patch in the queue and displays its content.
+.. _extensions: http://sphinx-doc.org/extensions.html
+.. _Quilt: http://savannah.nongnu.org/projects/quilt