From d6cbb24fcf6ad2a4306c0913b10b1f3c574bbcaa Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 1 Jan 2016 22:08:04 -0800 Subject: [PATCH] notmuch-report: Add notmuch-report(1) and notmuch-report.json(5) man pages To describe the script and config file format, so folks don't have to dig through NEWS or the script's source to get that information. The Makefile and conf.py are excerpted from the main doc/ directory with minor simplifications and adjustments. The devel/nmbug/ scripts are largely independent of notmuch, and separating the docs here allows packagers to easily build the docs and install the scripts in a separate package, without complicating notmuch's core build/install process. --- devel/nmbug/doc/.gitignore | 2 + devel/nmbug/doc/Makefile | 38 ++++++ devel/nmbug/doc/conf.py | 67 +++++++++ devel/nmbug/doc/index.rst | 17 +++ devel/nmbug/doc/man1/notmuch-report.1.rst | 54 ++++++++ .../nmbug/doc/man5/notmuch-report.json.5.rst | 129 ++++++++++++++++++ devel/nmbug/notmuch-report | 19 +-- 7 files changed, 318 insertions(+), 8 deletions(-) create mode 100644 devel/nmbug/doc/.gitignore create mode 100644 devel/nmbug/doc/Makefile create mode 100644 devel/nmbug/doc/conf.py create mode 100644 devel/nmbug/doc/index.rst create mode 100644 devel/nmbug/doc/man1/notmuch-report.1.rst create mode 100644 devel/nmbug/doc/man5/notmuch-report.json.5.rst diff --git a/devel/nmbug/doc/.gitignore b/devel/nmbug/doc/.gitignore new file mode 100644 index 00000000..4930881a --- /dev/null +++ b/devel/nmbug/doc/.gitignore @@ -0,0 +1,2 @@ +*.pyc +_build diff --git a/devel/nmbug/doc/Makefile b/devel/nmbug/doc/Makefile new file mode 100644 index 00000000..7ea3ae71 --- /dev/null +++ b/devel/nmbug/doc/Makefile @@ -0,0 +1,38 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +DOCBUILDDIR := _build + +SRCDIR ?= . +ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(SRCDIR) + +MAN_RST_FILES := $(shell find $(SRCDIR)/man* -name '*.rst') +MAN_ROFF_FILES := $(patsubst $(SRCDIR)/man%.rst,$(DOCBUILDDIR)/man/man%,$(MAN_RST_FILES)) +MAN_GZIP_FILES := $(addsuffix .gz,$(MAN_ROFF_FILES)) + +.PHONY: build-man +build-man: $(MAN_GZIP_FILES) + +%.gz: % + rm -f $@ && gzip --stdout $^ > $@ + +$(MAN_ROFF_FILES): $(DOCBUILDDIR)/.roff.stamp + +# By using $(DOCBUILDDIR)/.roff.stamp instead of $(MAN_ROFF_FILES), we +# convey to make that a single invocation of this recipe builds all +# of the roff files. This prevents parallel make from starting an +# instance of this recipe for each roff file. +$(DOCBUILDDIR)/.roff.stamp $(MAN_ROFF_FILES): $(MAN_RST_FILES) + mkdir -p $(DOCBUILDDIR) + touch $(DOCBUILDDIR)/.roff.stamp + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man + for section in 1 5; do \ + mkdir -p $(DOCBUILDDIR)/man/man$${section}; \ + mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \ + done + +clean: + rm -rf $(DOCBUILDDIR) $(SRCDIR)/conf.pyc diff --git a/devel/nmbug/doc/conf.py b/devel/nmbug/doc/conf.py new file mode 100644 index 00000000..29379d03 --- /dev/null +++ b/devel/nmbug/doc/conf.py @@ -0,0 +1,67 @@ +# -*- coding: utf-8 -*- + +import os.path + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'notmuch' +authors = 'Carl Worth and many others' +copyright = '2009-2015, {0}'.format(authors) + +location = os.path.dirname(__file__) + +dirname = location +while True: + version_file = os.path.join(dirname, 'version') + if os.path.exists(version_file): + with open(version_file,'r') as f: + version = f.read().strip() + break + if dirname == '/': + raise ValueError( + 'no version file found in this directory or its ancestors') + dirname = os.path.dirname(dirname) + +# The full version, including alpha/beta/rc tags. +release = version + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). + +man_pages = [ + ('man1/notmuch-report.1', 'notmuch-report', + 'generate reports from notmuch queries', [authors], 1), + ('man5/notmuch-report.json.5', 'notmuch-report.json', + 'configure notmuch-report', [authors], 5), +] + +# If true, show URL addresses after external links. +#man_show_urls = False + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +# If true, do not generate a @detailmenu in the "Top" node's menu. +texinfo_no_detailmenu = True + +texinfo_documents = [ + ('man1/notmuch-report.1', 'notmuch-report', + 'generate reports from notmuch queries', authors, 'notmuch-report', + 'generate reports from notmuch queries', 'Miscellaneous'), + ('man5/notmuch-report.json.5', 'notmuch-report.json', + 'configure notmuch-report', authors, 'notmuch-report.json', + 'configure notmuch-report', 'Miscellaneous'), +] diff --git a/devel/nmbug/doc/index.rst b/devel/nmbug/doc/index.rst new file mode 100644 index 00000000..51ac59ec --- /dev/null +++ b/devel/nmbug/doc/index.rst @@ -0,0 +1,17 @@ +Welcome to notmuch's dev-tool documentation! +============================================ + +Contents: + +.. toctree:: + :titlesonly: + + man1/notmuch-report.1 + man5/notmuch-report.json.5 + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/devel/nmbug/doc/man1/notmuch-report.1.rst b/devel/nmbug/doc/man1/notmuch-report.1.rst new file mode 100644 index 00000000..dfd82df3 --- /dev/null +++ b/devel/nmbug/doc/man1/notmuch-report.1.rst @@ -0,0 +1,54 @@ +============== +notmuch-report +============== + +SYNOPSIS +======== + +**notmuch-report** [options ...] + +DESCRIPTION +=========== + +Generate HTML or plain-text reports showing query results. + +OPTIONS +======= + + ``-h``, ``--help`` + + Show a help message, including a list of available options, and + exit. + + ``--text`` + Output plain text instead of HTML. + + ``--config`` + Load config from given file. The format is described in + **notmuch-report.json(5)**. If this option is not set, + **notmuch-report** loads the config from the Git repository at + ``NMBGIT``. See :ref:`NMBGIT ` for details. + + ``--list-views`` + List available views (by title) and exit. + + ``--get-query`` + Print the configured query for view matching the given title. + +ENVIRONMENT +=========== + +.. _NMBGIT: + + ``NMBGIT`` + If ``--config PATH`` is not set, **notmuch-report** will attempt + to load a config file named ``notmuch-report.json`` from the + ``config`` branch of the ``NMBGIT`` repository (defaulting to + ``~/.nmbug``). + +SEE ALSO +======== + +**notmuch(1)**, **notmuch-report.json(5)**, **notmuch-search(1)**, + **notmuch-tag(1)** + diff --git a/devel/nmbug/doc/man5/notmuch-report.json.5.rst b/devel/nmbug/doc/man5/notmuch-report.json.5.rst new file mode 100644 index 00000000..4b5f84a8 --- /dev/null +++ b/devel/nmbug/doc/man5/notmuch-report.json.5.rst @@ -0,0 +1,129 @@ +============== +notmuch-report +============== + +NAME +==== + +notmuch-report.json - configure output for **notmuch-report(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 nmbug", + "header": "

{title}

{blurb}

Views

", + "footer": "

Generated: {datetime}

", + "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)" + ] + } + ] + } + +SEE ALSO +======== + +**notmuch(1)**, **notmuch-report(1)**, **notmuch-search(1)**, **notmuch-tag(1)** diff --git a/devel/nmbug/notmuch-report b/devel/nmbug/notmuch-report index 8ddcf41c..87390c1e 100755 --- a/devel/nmbug/notmuch-report +++ b/devel/nmbug/notmuch-report @@ -310,14 +310,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 notmuch-report.json(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() -- 2.26.2