Commits

masklinn  committed 687de44

Doc core with queue/patch examples, basic configuration of noop directives

  • Participants
  • Parent commits 47b0ac5

Comments (0)

Files changed (20)

File doc/.pc/.quilt_patches

+patches

File doc/.pc/.quilt_series

+series

File doc/.pc/.version

+2

File doc/.pc/applied-patches

+purpose
+configuration
+printing
+more-patches

File doc/.pc/configuration/.timestamp

Empty file added.

File doc/.pc/configuration/index.rst

+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.
+
+.. _Mercurial Queues:
+    http://mercurial.selenic.com/wiki/MqExtension
+
+.. _Quilt: http://savannah.nongnu.org/projects/quilt

File doc/.pc/more-patches/.timestamp

Empty file added.

File doc/.pc/more-patches/index.rst

+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.
+
+Configuration
+-------------
+
+.. 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
+files, in order).
+
+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
+(with context).
+
+.. patch::
+
+API
+---
+
+.. 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
+
+.. _Mercurial Queues:
+    http://mercurial.selenic.com/wiki/MqExtension
+
+.. _Quilt: http://savannah.nongnu.org/projects/quilt

File doc/.pc/printing/.timestamp

Empty file added.

File doc/.pc/printing/index.rst

+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.
+
+Configuration
+-------------
+
+.. 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
+files, in order).
+
+API
+---
+
+.. 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.
+
+.. _extensions: http://sphinx-doc.org/extensions.html
+
+.. _Mercurial Queues:
+    http://mercurial.selenic.com/wiki/MqExtension
+
+.. _Quilt: http://savannah.nongnu.org/projects/quilt

File doc/.pc/purpose/.timestamp

Empty file added.

File doc/.pc/purpose/index.rst

+.. 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!
+=============================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', '.pc']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

File doc/index.rst

-.. 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!
 =============================================
 
-Contents:
+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.
 
-.. toctree::
-   :maxdepth: 2
+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.
 
+Configuration
+-------------
 
+.. queue:: patches/series
 
-Indices and tables
-==================
+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
+files, in order).
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. 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
+(with context).
+
+.. 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.
+
+.. patch::
+
+.. patch::
+
+API
+---
+
+.. 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
+
+.. _Mercurial Queues:
+    http://mercurial.selenic.com/wiki/MqExtension
+
+.. _Quilt: http://savannah.nongnu.org/projects/quilt

File doc/patches/configuration

+Index: doc/index.rst
+===================================================================
+--- doc.orig/index.rst
++++ doc/index.rst
+@@ -16,6 +16,29 @@ the evolution of the tutorial itself and
+ (such as typos at various steps of the example) is captured by the
+ wider versioning of the document.
+ 
++Configuration
++-------------
++
++.. 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
++files, in order).
++
++API
++---
++
++.. 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.
++
++.. _extensions: http://sphinx-doc.org/extensions.html
++
+ .. _Mercurial Queues:
+     http://mercurial.selenic.com/wiki/MqExtension
+ 

File doc/patches/more-patches

+Index: doc/index.rst
+===================================================================
+--- doc.orig/index.rst
++++ doc/index.rst
+@@ -27,6 +27,8 @@ to configure the patch queue for the cur
+ the (relative) path to a "series" file (file listing the queue's patch
+ files, in order).
+ 
++.. patch::
++
+ Displaying patch sequences
+ --------------------------
+ 
+@@ -38,6 +40,17 @@ filtered if necessary to only show the l
+ 
+ .. 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.
++
++.. patch::
++
++.. patch::
++
+ API
+ ---
+ 

File doc/patches/printing

+Index: doc/index.rst
+===================================================================
+--- doc.orig/index.rst
++++ doc/index.rst
+@@ -27,6 +27,17 @@ to configure the patch queue for the cur
+ the (relative) path to a "series" file (file listing the queue's patch
+ files, in order).
+ 
++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
++(with context).
++
++.. patch::
++
+ API
+ ---
+ 
+@@ -37,6 +48,10 @@ API
+ 
+     :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
+ 
+ .. _Mercurial Queues:

File doc/patches/purpose

+Index: doc/index.rst
+===================================================================
+--- doc.orig/index.rst
++++ doc/index.rst
+@@ -1,22 +1,22 @@
+-.. 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!
+ =============================================
+ 
+-Contents:
+-
+-.. toctree::
+-   :maxdepth: 2
+-
+-
+-
+-Indices and tables
+-==================
++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.
+ 
+-* :ref:`genindex`
+-* :ref:`modindex`
+-* :ref:`search`
++.. _Mercurial Queues:
++    http://mercurial.selenic.com/wiki/MqExtension
+ 
++.. _Quilt: http://savannah.nongnu.org/projects/quilt

File doc/patches/series

+purpose
+configuration
+printing
+more-patches

File patchqueue.py

+from docutils import nodes
+from docutils.parsers import rst
+import sphinx.directives
+
+
+def setup(app):
+    app.add_node(queue)
+    app.add_node(patch)
+
+    app.add_directive('queue', Queue)
+    app.add_directive('patch', Patch)
+
+
+class queue(nodes.General, nodes.Element):
+    pass
+
+
+class patch(nodes.General, nodes.Element):
+    pass
+
+
+class Queue(rst.Directive):
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+
+    def run(self):
+        # self.state.document.settings.env.docname
+        return []
+
+
+class Patch(rst.Directive):
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+
+    def run(self):
+        return []
+        root = nodes.container(classes=['my-hook-class'])
+
+        # Take "next" patch (in current queue)
+        # read patchfile
+        # apply patchfile to queue tempdir
+
+        # extract offset from patch "result", filter affected files, highlight
+        #  altered section (if visible)... add container these and a code
+        #  block per file for path prefix?
+        sectioned_source = sphinx.directives.CodeBlock()
+        root.extend(sectioned_source.run())
+
+        # display patchfile as patch (with per-file prefix?)
+        diff_source = sphinx.directives.CodeBlock()
+        root.extend(diff_source.run())
+
+        # Display each affected file (with per-file prefix?)
+        full_source = sphinx.directives.CodeBlock()
+        root.extend(full_source.run())
+
+        return [root]