Browse Source

docs: improved cli docs

whitelist
Sebastian Heimann 3 years ago
parent
commit
a9d512a651
  1. 19
      docs/Makefile
  2. 4
      docs/source/cli/check.rst
  3. 4
      docs/source/cli/diff.rst
  4. 4
      docs/source/cli/events.rst
  5. 4
      docs/source/cli/export.rst
  6. 4
      docs/source/cli/forward.rst
  7. 4
      docs/source/cli/go.rst
  8. 4
      docs/source/cli/harvest.rst
  9. 19
      docs/source/cli/index.rst
  10. 4
      docs/source/cli/init.rst
  11. 4
      docs/source/cli/movie.rst
  12. 4
      docs/source/cli/plot.rst
  13. 4
      docs/source/cli/qc-polarization.rst
  14. 4
      docs/source/cli/report.rst
  15. 4
      docs/source/cli/scenario.rst
  16. 4
      docs/source/cli/upgrade-config.rst
  17. 4
      docs/source/cli/version.rst
  18. 2
      docs/source/index.rst
  19. 16
      docs/source/overview/index.rst
  20. 71
      src/apps/grond.py

19
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)
%: Makefile source/cli/scenario.rst
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

4
docs/source/cli/check.rst

@ -1,4 +0,0 @@
check
-----
.. command-output:: grond check --help

4
docs/source/cli/diff.rst

@ -1,4 +0,0 @@
diff
----
.. command-output:: grond diff --help

4
docs/source/cli/events.rst

@ -1,4 +0,0 @@
events
------
.. command-output:: grond events --help

4
docs/source/cli/export.rst

@ -1,4 +0,0 @@
export
------
.. command-output:: grond export --help

4
docs/source/cli/forward.rst

@ -1,4 +0,0 @@
forward
-------
.. command-output:: grond forward --help

4
docs/source/cli/go.rst

@ -1,4 +0,0 @@
go
--
.. command-output:: grond go --help

4
docs/source/cli/harvest.rst

@ -1,4 +0,0 @@
harvest
-------
.. command-output:: grond harvest --help

19
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
(``<placeholder>``), 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

4
docs/source/cli/init.rst

@ -1,4 +0,0 @@
init
----
.. command-output:: grond init --help

4
docs/source/cli/movie.rst

@ -1,4 +0,0 @@
movie
-----
.. command-output:: grond movie --help

4
docs/source/cli/plot.rst

@ -1,4 +0,0 @@
plot
----
.. command-output:: grond plot --help

4
docs/source/cli/qc-polarization.rst

@ -1,4 +0,0 @@
qc-polarization
---------------
.. command-output:: grond qc-polarization --help

4
docs/source/cli/report.rst

@ -1,4 +0,0 @@
report
------
.. command-output:: grond report --help

4
docs/source/cli/scenario.rst

@ -1,4 +0,0 @@
scenario
--------
.. command-output:: grond scenario --help

4
docs/source/cli/upgrade-config.rst

@ -1,4 +0,0 @@
upgrade-config
--------------
.. command-output:: grond upgrade-config --help

4
docs/source/cli/version.rst

@ -1,4 +0,0 @@
version
-------
.. command-output:: grond version --help

2
docs/source/index.rst

@ -36,7 +36,7 @@ Contents
method/index
config/index
report/index
commands/index
cli/index
library/index

16
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:

71
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

Loading…
Cancel
Save