From: W. Trevor King Date: Sat, 2 Jan 2016 06:08:04 +0000 (+1600) Subject: [PATCH 4/5] notmuch-report: Add notmuch-report(1) and notmuch-report.json(5) man... X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=b63fae95cd17896b79969a21b35f401c2681b6d6;p=notmuch-archives.git [PATCH 4/5] notmuch-report: Add notmuch-report(1) and notmuch-report.json(5) man pages --- diff --git a/00/27ebdf9d2dabfb98553718589e8e97083bae94 b/00/27ebdf9d2dabfb98553718589e8e97083bae94 new file mode 100644 index 000000000..33f62ac11 --- /dev/null +++ b/00/27ebdf9d2dabfb98553718589e8e97083bae94 @@ -0,0 +1,474 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by arlo.cworth.org (Postfix) with ESMTP id CA5C16DE1B42 + for ; Fri, 1 Jan 2016 22:10:39 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at cworth.org +X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" +X-Spam-Flag: NO +X-Spam-Score: 0.04 +X-Spam-Level: +X-Spam-Status: No, score=0.04 tagged_above=-999 required=5 tests=[AWL=0.042, + DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, + RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001] autolearn=disabled +Received: from arlo.cworth.org ([127.0.0.1]) + by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id QAcMTDmpZfDU for ; + Fri, 1 Jan 2016 22:10:37 -0800 (PST) +Received: from resqmta-po-02v.sys.comcast.net (resqmta-po-02v.sys.comcast.net + [96.114.154.161]) + by arlo.cworth.org (Postfix) with ESMTPS id 2C48D6DE1A2E + for ; Fri, 1 Jan 2016 22:10:02 -0800 (PST) +Received: from resomta-po-03v.sys.comcast.net ([96.114.154.227]) + by resqmta-po-02v.sys.comcast.net with comcast + id 0uA11s0014ueUHc01uA193; Sat, 02 Jan 2016 06:10:01 +0000 +Received: from mail.tremily.us ([73.221.72.168]) + by resomta-po-03v.sys.comcast.net with comcast + id 0u801s0043dr3C901u80EX; Sat, 02 Jan 2016 06:08:00 +0000 +Received: from ullr.tremily.us (unknown [192.168.10.7]) + by mail.tremily.us (Postfix) with ESMTPS id DC8EA1B2F583; + Fri, 1 Jan 2016 22:07:59 -0800 (PST) +Received: (nullmailer pid 15185 invoked by uid 1000); + Sat, 02 Jan 2016 06:08:07 -0000 +From: "W. Trevor King" +To: notmuch@notmuchmail.org +Cc: David Bremner , + Tomi Ollila , Jani Nikula , + Carl Worth , "W. Trevor King" +Subject: [PATCH 4/5] notmuch-report: Add notmuch-report(1) and + notmuch-report.json(5) man pages +Date: Fri, 1 Jan 2016 22:08:04 -0800 +Message-Id: + +X-Mailer: git-send-email 2.1.0.60.g85f0837 +In-Reply-To: +References: +In-Reply-To: +References: +DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; + s=q20140121; t=1451715001; + bh=I0GQKQ8byzorNKmWV7mN2GEJCbEvkR8d1BzWag3Kt34=; + h=Received:Received:Received:Received:From:To:Subject:Date: + Message-Id; + b=gagI4xIW51Zq95fvmDFALnqtSBWfzysPC0PfBuTJ8m9tam6obtU6KkHNzQfUS5+HA + 0Rlxf++kh5/ooTHY7Fj5IDIGZz9+4nSPYCCDDFFYJ/mlUJVl0TTguv82JAXqecBnW0 + OBIBac83KHo9O9snLF2XKOOLPyel7va3TwXv62dNK/ljGlgDiYF3isU8CQT7NoIQ6U + BmSB/9REUaKHVTn+qpbe7xx6eJbwAYRB/WFL9q+xRYdGTzG5h7b6Xd22WNb42DPJUq + Dht7Zh1IhOuWuYyBI5ILir10M6DiJj2jAys7AA7WyLrwZC0TtwjOvGgKMxWXHWAHWp + hYK8y+gZmuxcw== +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.20 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Sat, 02 Jan 2016 06:10:40 -0000 + +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 +++++++++++ + devel/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 0000000..4930881 +--- /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 0000000..7ea3ae7 +--- /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 0000000..29379d0 +--- /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 0000000..51ac59e +--- /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 0000000..dfd82df +--- /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 0000000..4b5f84a +--- /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 5425e06..a4a3197 100755 +--- a/devel/nmbug/notmuch-report ++++ b/devel/nmbug/notmuch-report +@@ -304,14 +304,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.1.0.60.g85f0837 +