From a9d512a65185639d9aa21b51c10657e35833a3a9 Mon Sep 17 00:00:00 2001 From: Sebastian Heimann Date: Fri, 10 Aug 2018 16:05:18 +0200 Subject: [PATCH] docs: improved cli docs --- docs/Makefile | 19 +++++++- docs/source/cli/check.rst | 4 -- docs/source/cli/diff.rst | 4 -- docs/source/cli/events.rst | 4 -- docs/source/cli/export.rst | 4 -- docs/source/cli/forward.rst | 4 -- docs/source/cli/go.rst | 4 -- docs/source/cli/harvest.rst | 4 -- docs/source/cli/index.rst | 19 ++++---- docs/source/cli/init.rst | 4 -- docs/source/cli/movie.rst | 4 -- docs/source/cli/plot.rst | 4 -- docs/source/cli/qc-polarization.rst | 4 -- docs/source/cli/report.rst | 4 -- docs/source/cli/scenario.rst | 4 -- docs/source/cli/upgrade-config.rst | 4 -- docs/source/cli/version.rst | 4 -- docs/source/index.rst | 2 +- docs/source/overview/index.rst | 16 +++---- src/apps/grond.py | 71 ++++++++++++++++++++++++++++- 20 files changed, 106 insertions(+), 81 deletions(-) delete mode 100644 docs/source/cli/check.rst delete mode 100644 docs/source/cli/diff.rst delete mode 100644 docs/source/cli/events.rst delete mode 100644 docs/source/cli/export.rst delete mode 100644 docs/source/cli/forward.rst delete mode 100644 docs/source/cli/go.rst delete mode 100644 docs/source/cli/harvest.rst delete mode 100644 docs/source/cli/init.rst delete mode 100644 docs/source/cli/movie.rst delete mode 100644 docs/source/cli/plot.rst delete mode 100644 docs/source/cli/qc-polarization.rst delete mode 100644 docs/source/cli/report.rst delete mode 100644 docs/source/cli/scenario.rst delete mode 100644 docs/source/cli/upgrade-config.rst delete mode 100644 docs/source/cli/version.rst diff --git a/docs/Makefile b/docs/Makefile index 45d70c5..9daaefe 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,13 +8,28 @@ SPHINXPROJ = grond SOURCEDIR = source BUILDDIR = build +GRONDCOMMANDS = scenario init events check go forward harvest plot movie \ + export report diff qc-polarization upgrade-config version + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile +source/cli/scenario.rst: + for cmd in $(GRONDCOMMANDS) ; do \ + grond $$cmd --docs > source/cli/$${cmd}.rst ; \ + done + + +clean: + for cmd in $(GRONDCOMMANDS) ; do \ + rm source/cli/$${cmd}.rst ; \ + done + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file +%: Makefile source/cli/scenario.rst + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/cli/check.rst b/docs/source/cli/check.rst deleted file mode 100644 index 8606322..0000000 --- a/docs/source/cli/check.rst +++ /dev/null @@ -1,4 +0,0 @@ -check ------ - -.. command-output:: grond check --help diff --git a/docs/source/cli/diff.rst b/docs/source/cli/diff.rst deleted file mode 100644 index 580d1ea..0000000 --- a/docs/source/cli/diff.rst +++ /dev/null @@ -1,4 +0,0 @@ -diff ----- - -.. command-output:: grond diff --help diff --git a/docs/source/cli/events.rst b/docs/source/cli/events.rst deleted file mode 100644 index 699289f..0000000 --- a/docs/source/cli/events.rst +++ /dev/null @@ -1,4 +0,0 @@ -events ------- - -.. command-output:: grond events --help diff --git a/docs/source/cli/export.rst b/docs/source/cli/export.rst deleted file mode 100644 index 6925159..0000000 --- a/docs/source/cli/export.rst +++ /dev/null @@ -1,4 +0,0 @@ -export ------- - -.. command-output:: grond export --help diff --git a/docs/source/cli/forward.rst b/docs/source/cli/forward.rst deleted file mode 100644 index b6ac676..0000000 --- a/docs/source/cli/forward.rst +++ /dev/null @@ -1,4 +0,0 @@ -forward -------- - -.. command-output:: grond forward --help diff --git a/docs/source/cli/go.rst b/docs/source/cli/go.rst deleted file mode 100644 index 23b658e..0000000 --- a/docs/source/cli/go.rst +++ /dev/null @@ -1,4 +0,0 @@ -go --- - -.. command-output:: grond go --help diff --git a/docs/source/cli/harvest.rst b/docs/source/cli/harvest.rst deleted file mode 100644 index d5095de..0000000 --- a/docs/source/cli/harvest.rst +++ /dev/null @@ -1,4 +0,0 @@ -harvest -------- - -.. command-output:: grond harvest --help diff --git a/docs/source/cli/index.rst b/docs/source/cli/index.rst index 528392b..58bbc72 100644 --- a/docs/source/cli/index.rst +++ b/docs/source/cli/index.rst @@ -2,19 +2,22 @@ Command line interface ====================== Grond is a normally invoked as a command line program by calling ``grond`` from -the Unix/Linux shell. It's command line interface (CLI) uses the standard -Unix/Linux conventions for its options and arguments. To get a brief summary -on any of its subcommands, add the ``--help`` option. Options are recognized by -their leading double-dashes, e.g. ``--help``. Some options in Grond have short aliases -with single dashes. +the Unix/Linux shell. Its command line interface (CLI) uses standard Unix/Linux +conventions for its options and arguments. To get a brief summary on any Grond +subcommand, add the ``--help`` option. Options are recognized by their leading +double-dashes (``--help``). Some options have single character aliases names +accessible with single dash notation (``-h``). In the documentation, +placeholders for required arguments are denoted with angle brackets +(````), placeholders for optional arguments with square brackets, +e.g. (``[placeholder]``). .. command-output:: grond --help -Grond subcommands ------------------ +The following pages list the self-documentation strings of all Grond +subcommands. .. toctree:: - :caption: Subcommands: + :maxdepth: 1 scenario init diff --git a/docs/source/cli/init.rst b/docs/source/cli/init.rst deleted file mode 100644 index c29ba26..0000000 --- a/docs/source/cli/init.rst +++ /dev/null @@ -1,4 +0,0 @@ -init ----- - -.. command-output:: grond init --help diff --git a/docs/source/cli/movie.rst b/docs/source/cli/movie.rst deleted file mode 100644 index e75cccf..0000000 --- a/docs/source/cli/movie.rst +++ /dev/null @@ -1,4 +0,0 @@ -movie ------ - -.. command-output:: grond movie --help diff --git a/docs/source/cli/plot.rst b/docs/source/cli/plot.rst deleted file mode 100644 index 8a59973..0000000 --- a/docs/source/cli/plot.rst +++ /dev/null @@ -1,4 +0,0 @@ -plot ----- - -.. command-output:: grond plot --help diff --git a/docs/source/cli/qc-polarization.rst b/docs/source/cli/qc-polarization.rst deleted file mode 100644 index 30d331f..0000000 --- a/docs/source/cli/qc-polarization.rst +++ /dev/null @@ -1,4 +0,0 @@ -qc-polarization ---------------- - -.. command-output:: grond qc-polarization --help diff --git a/docs/source/cli/report.rst b/docs/source/cli/report.rst deleted file mode 100644 index e479cd3..0000000 --- a/docs/source/cli/report.rst +++ /dev/null @@ -1,4 +0,0 @@ -report ------- - -.. command-output:: grond report --help diff --git a/docs/source/cli/scenario.rst b/docs/source/cli/scenario.rst deleted file mode 100644 index cf66c2c..0000000 --- a/docs/source/cli/scenario.rst +++ /dev/null @@ -1,4 +0,0 @@ -scenario --------- - -.. command-output:: grond scenario --help diff --git a/docs/source/cli/upgrade-config.rst b/docs/source/cli/upgrade-config.rst deleted file mode 100644 index 42bd381..0000000 --- a/docs/source/cli/upgrade-config.rst +++ /dev/null @@ -1,4 +0,0 @@ -upgrade-config --------------- - -.. command-output:: grond upgrade-config --help diff --git a/docs/source/cli/version.rst b/docs/source/cli/version.rst deleted file mode 100644 index ae7d9a0..0000000 --- a/docs/source/cli/version.rst +++ /dev/null @@ -1,4 +0,0 @@ -version -------- - -.. command-output:: grond version --help diff --git a/docs/source/index.rst b/docs/source/index.rst index fe30ebb..6ddd339 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -36,7 +36,7 @@ Contents method/index config/index report/index - commands/index + cli/index library/index diff --git a/docs/source/overview/index.rst b/docs/source/overview/index.rst index a5638e5..c2b86b3 100644 --- a/docs/source/overview/index.rst +++ b/docs/source/overview/index.rst @@ -17,10 +17,10 @@ The basic work-flow when using Grond is as follows: 1. Set up a project folder containing input data and Green's functions. 2. Set up a configuration file for Grond. -3. Check the set-up with ``grond check``. -4. Run the optimisation with ``grond go``. -5. Create result plots and report with ``grond report``. -6. Export results with ``grond export``. +3. Check the set-up with :option:`grond check`. +4. Run the optimisation with :option:`grond go`. +5. Create result plots and report with :option:`grond report`. +6. Export results with :option:`grond check`. Details on these steps are given in the following sections. @@ -146,10 +146,10 @@ strategies. A seismic event which has a unique name among all events available to a specific configuration of Grond. An event usually has a preliminary origin location and sometimes a reference mechanism attached to it. Config file - A `YAML`_ file, by convention ending with the suffix ``.gronf``, containing a Grond configuration. The config file can be made to work with multiple events. It can be generated using ``grond init``. + A `YAML`_ file, by convention ending with the suffix ``.gronf``, containing a Grond configuration. The config file can be made to work with multiple events. It can be generated using :option:`grond init`. Rundir - The directory, by convention ending with the suffix ``.grun``, where Grond stores intermediate and final results during an optimisation run. The rundir is created by Grond when running the ``grond go`` subcommand. + The directory, by convention ending with the suffix ``.grun``, where Grond stores intermediate and final results during an optimisation run. The rundir is created by Grond when running the :option:`grond go` subcommand. Dataset The dataset is a section in the config file telling Grond where to look for input data (waveforms, InSAR scenes, GNSS data) and meta-data (station coordinates, instrument responses, blacklists, picks, event catalogues, etc.). @@ -191,7 +191,7 @@ modelled (section :ref:`project-scenario`). Initializing an empty project ............................. -An empty project structure can be created with the subcommand ``grond init``. Different configurations can be added by flags, see ``grond init --help`` for more information. +An empty project structure can be created with the subcommand :option:`grond init`. Different configurations can be added by flags, see ``grond init --help`` for more information. .. code-block :: sh @@ -232,7 +232,7 @@ The ``targets`` (data and misfit setups for seismic waveforms, InSAR and or GNSS Initializing a scenario project from forward modelling ...................................................... -The subcommand ``grond scenario`` will forward model observations for a modelled earthquake and create a ready-to-go Grond project. Different observations and source problems can be added by flags - see ``grond scenario --help`` for possible combinations and options. +The subcommand :option:`grond scenario` will forward model observations for a modelled earthquake and create a ready-to-go Grond project. Different observations and source problems can be added by flags - see ``grond scenario --help`` for possible combinations and options. The scenario can contain the following synthetic observations: diff --git a/src/apps/grond.py b/src/apps/grond.py index 4c6a1ef..54f71a8 100755 --- a/src/apps/grond.py +++ b/src/apps/grond.py @@ -181,9 +181,76 @@ def add_common_options(parser): '"critical", "error", "warning", "info", or "debug". ' 'Default is "%default".') + parser.add_option( + '--docs', + dest='rst_docs', + action='store_true') + + +def print_docs(command, parser): + + from optparse import IndentedHelpFormatter + + class DocsFormatter(IndentedHelpFormatter): + + def format_heading(self, heading): + return '%s\n%s\n\n' % (heading, '.'*len(heading)) + + def format_usage(self, usage): + lines = usage.splitlines() + return self.format_heading('Usage') + \ + '.. code-block:: none\n\n%s' % '\n'.join( + ' '+line.strip() for line in lines) + + def format_option(self, option): + if not option.help: + return '' + + result = [] + opts = self.option_strings[option] + result.append('\n.. describe:: %s\n\n' % opts) + + help_text = self.expand_default(option) + result.append(' %s\n\n' % help_text) + + return ''.join(result) + + parser.formatter = DocsFormatter() + parser.formatter.set_parser(parser) + + def format_help(parser): + formatter = parser.formatter + result = [] + + result.append(parser.format_description(formatter) + "\n") + + if parser.usage: + result.append(parser.get_usage() + "\n") + + result.append('\n') + + result.append(parser.format_option_help(formatter)) + + result.append('\n') + + result.append(parser.format_epilog(formatter)) + return "".join(result) + + print(command) + print('-' * len(command)) + print() + print('.. program:: %s' % program_name) + print() + print('.. option:: %s' % command) + print() + print(format_help(parser)) + -def process_common_options(options): +def process_common_options(command, parser, options): util.setup_logging(program_name, options.loglevel) + if options.rst_docs: + print_docs(command, parser) + exit(0) def cl_parse(command, args, setup=None, details=None): @@ -209,7 +276,7 @@ def cl_parse(command, args, setup=None, details=None): add_common_options(parser) (options, args) = parser.parse_args(args) - process_common_options(options) + process_common_options(command, parser, options) return parser, options, args