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 _______________________________________________ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch