[PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

Subject: [PATCH 3/5] nmbug-status: Add an nmbug-status(5) man page

Date: Wed, 30 Dec 2015 11:16:58 -0800

To: notmuch@notmuchmail.org

Cc: David Bremner, Tomi Ollila, Jani Nikula, Carl Worth, W. Trevor King

From: W. Trevor King


To describe the config file format, so folks don't have to dig through
NEWS or the nmbug-status source to get that information.
---
 NEWS                      |   5 ++
 devel/nmbug/nmbug-status  |  19 ++++---
 doc/conf.py               |   6 ++
 doc/index.rst             |   1 +
 doc/man5/nmbug-status.rst | 136 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 159 insertions(+), 8 deletions(-)
 create mode 100644 doc/man5/nmbug-status.rst

diff --git a/NEWS b/NEWS
index 9f2e860..9a6a757 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,11 @@
 Notmuch 0.22 (UNRELEASED)
 =========================
 
+Documentation
+-------------
+
+A new `nmbug-status(5)` describes `nmbug-status`'s JSON config file.
+
 nmbug-status
 ------------
 
diff --git a/devel/nmbug/nmbug-status b/devel/nmbug/nmbug-status
index d72f1db..336d0d2 100755
--- a/devel/nmbug/nmbug-status
+++ b/devel/nmbug/nmbug-status
@@ -309,14 +309,17 @@ class HtmlPage (Page):
         return self._slug_regexp.sub('-', string)
 
 parser = argparse.ArgumentParser(description=__doc__)
-parser.add_argument('--text', help='output plain text format',
-                    action='store_true')
-parser.add_argument('--config', help='load config from given file',
-                    metavar='PATH')
-parser.add_argument('--list-views', help='list views',
-                    action='store_true')
-parser.add_argument('--get-query', help='get query for view',
-                    metavar='VIEW')
+parser.add_argument(
+    '--text', action='store_true', help='output plain text format')
+parser.add_argument(
+    '--config', metavar='PATH',
+    help='load config from given file.  '
+        'The format is described in nmbug-status(5).')
+parser.add_argument(
+    '--list-views', action='store_true', help='list views')
+parser.add_argument(
+    '--get-query', metavar='VIEW', help='get query for view')
+
 
 args = parser.parse_args()
 
diff --git a/doc/conf.py b/doc/conf.py
index 65adafe..eac747e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -118,6 +118,9 @@ man_pages = [
         u'add/remove tags for all messages matching the search terms',
         [u'Carl Worth and many others'], 1),
 
+('man5/nmbug-status','nmbug-status',
+        u'configuration for nmbug-status',
+        [u'Carl Worth and many others'], 5),
 
 ]
 # If true, show URL addresses after external links.
@@ -180,4 +183,7 @@ texinfo_documents = [
 ('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
       u'Carl Worth and many others', 'notmuch-tag',
       'add/remove tags for all messages matching the search terms','Miscellaneous'),
+('man5/nmbug-status','nmbug-status',u'notmuch Documentation',
+      u'Carl Worth and many others', 'nmbug-status',
+      'configuration for nmbug-status','Miscellaneous'),
 ]
diff --git a/doc/index.rst b/doc/index.rst
index 3f0e6e6..bcb1dd0 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -23,6 +23,7 @@ Contents:
    man7/notmuch-search-terms
    man1/notmuch-show
    man1/notmuch-tag
+   man5/nmbug-status
 
 Indices and tables
 ==================
diff --git a/doc/man5/nmbug-status.rst b/doc/man5/nmbug-status.rst
new file mode 100644
index 0000000..5b59bdd
--- /dev/null
+++ b/doc/man5/nmbug-status.rst
@@ -0,0 +1,136 @@
+============
+nmbug-status
+============
+
+NAME
+====
+
+status-config.json - configure output for **nmbug-status(1)**
+
+DESCRIPTION
+===========
+
+The config file is JSON_ with the following fields:
+
+meta
+  An object with page-wide information
+
+  title
+    Page title used in the default header.
+
+  blurb
+    Introduction paragraph used in the default header.
+
+  header
+    `Python format string`_ for the HTML header.  Optional.  It is
+    formatted with the following context:
+
+    date
+      The current UTC date.
+
+    datetime
+      The current UTC date-time.
+
+    title
+      The **meta.title** value.
+
+    blurb
+      The **meta.blurb** value.
+
+    encoding
+      The encoding used for the output file.
+
+    inter_message_padding
+      0.25em, for consistent CSS generation.
+
+    border_radius
+      0.5em, for consistent CSS generation.
+
+  footer
+    `Python format string`_ for the HTML footer.  It is formatted with
+    the same context used for **meta.header**.  Optional.
+
+  message-url
+    `Python format string`_ for message-linking URLs.  Optional.
+    Defaults to linking Gmane_.  It is formatted with the following
+    context:
+
+    message-id
+      The quoted_ message ID.
+
+    subject
+      The message subject.
+
+views
+  An array of view objects, where each object has the following
+  fields:
+
+  title
+    Header text for the view.
+
+  comment
+    Paragraph describing the view in more detail.  Optional.
+
+  id
+    Anchor string for the view.  Optional, defaulting to a slugged
+    form of the view title
+
+  query
+    An array of strings, which will be joined with 'and' to form the
+    view query.
+
+.. _Gmane: http://gmane.org/
+.. _JSON: http://json.org/
+.. _Python format string: https://docs.python.org/3/library/string.html#formatstrings
+.. _quoted: https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote
+
+EXAMPLE
+=======
+
+::
+
+  {
+    "meta": {
+      "title": "Notmuch Patches",
+      "blurb": "For more information see <a href=\"http://notmuchmail.org/nmbug\">nmbug</a>",
+      "header": "<html><head></head><body><h1>{title}</h1><p>{blurb}</p><h2>Views</h2>",
+      "footer": "<hr><p>Generated: {datetime}</p></html>",
+      "message-url": "http://mid.gmane.org/{message-id}"
+    },
+    "views": [
+      {
+        "title": "Bugs",
+        "comment": "Unresolved bugs.",
+        "query": [
+          "tag:notmuch::bug",
+          "not tag:notmuch::fixed",
+          "not tag:notmuch::wontfix"
+        ]
+      },
+      {
+        "title": "Review",
+        "comment": "These patches are under review, or waiting for feedback.",
+        "id": "under-review",
+        "query": [
+          "tag:notmuch::patch",
+          "not tag:notmuch::pushed",
+          "not tag:notmuch::obsolete",
+          "not tag:notmuch::stale",
+          "not tag:notmuch::wontfix",
+          "(tag:notmuch::moreinfo or tag:notmuch::needs-review)"
+        ]
+      }
+    ]
+  }
+
+FILES
+=====
+
+If ``--config PATH`` is not set, ``nmbug-status`` will attempt to load
+a config file named ``status-config.json`` from the ``config`` branch
+of the ``NMBGIT`` repository (defaulting to ``~/.nmbug``).
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-search(1)**, **notmuch-tag(1)**
-- 
2.1.0.60.g85f0837


Thread: