From f129c2e22742e5c4501b13e9cda093fdd70b062b Mon Sep 17 00:00:00 2001 From: John Siirola Date: Wed, 18 Mar 2020 01:27:56 -0600 Subject: [PATCH] Docstring formatting updates --- pyutilib/misc/config.py | 50 +++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/pyutilib/misc/config.py b/pyutilib/misc/config.py index be3bc012..b011ca51 100644 --- a/pyutilib/misc/config.py +++ b/pyutilib/misc/config.py @@ -7,13 +7,13 @@ # the U.S. Government retains certain rights in this software. # _________________________________________________________________________ -""" -================================= +"""================================= The PyUtilib Configuration System ================================= -The PyUtilib config system provides a set of three classes (ConfigDict, -ConfigList, and ConfigValue) for managing and documenting structured +The PyUtilib config system provides a set of three classes +(:py:class:`ConfigDict`, :py:class:`ConfigList`, and +:py:class:`ConfigValue`) for managing and documenting structured configuration information and user input. The system is based around the ConfigValue class, which provides storage for a single configuration entry. ConfigValue objects can be grouped using two containers @@ -75,7 +75,7 @@ >>> print(config.iteration_limit) 20 -All Config objects support a `domain` keyword that accepts a callable +All Config objects support a ``domain`` keyword that accepts a callable object (type, function, or callable instance). The domain callable should take data and map it onto the desired domain, optionally performing domain validation (see :py:class:`ConfigValue`, @@ -95,7 +95,7 @@ ============================= A feature of the Config system is that the core classes all implement -`__call__`, and can themselves be used as `domain` values. Beyond +``__call__``, and can themselves be used as ``domain`` values. Beyond providing domain verification for complex hierarchical structures, this feature allows ConfigDicts to cleanly support the configuration of derived objects. Consider the following example: @@ -125,24 +125,24 @@ filename: input.txt pattern: .*warning -Here, the base class `Base` declares a class-level attribute CONFIG as a -ConfigDict containing a single entry (`filename`). The derived class -(`Derived`) then starts by making a copy of the base class' `CONFIG`, +Here, the base class ``Base`` declares a class-level attribute CONFIG as a +ConfigDict containing a single entry (``filename``). The derived class +(``Derived``) then starts by making a copy of the base class' ``CONFIG``, and then defines an additional entry (`pattern`). Instances of the base -class will still create `c` instances that only have the single -`filename` entry, whereas instances of the derived class will have `c` -instances with two entries: the `pattern` entry declared by the derived -class, and the `filename` entry "inherited" from the base class. +class will still create ``c`` instances that only have the single +``filename`` entry, whereas instances of the derived class will have ``c`` +instances with two entries: the ``pattern`` entry declared by the derived +class, and the ``filename`` entry "inherited" from the base class. An extension of this design pattern provides a clean approach for handling "ephemeral" instance options. Consider an interface to an -external "solver". Our class implements a `solve()` method that takes a +external "solver". Our class implements a ``solve()`` method that takes a problem and sends it to the solver along with some solver configuration options. We would like to be able to set those options "persistently" on instances of the interface class, but still override them -"temporarily" for individual calls to `solve()`. We implement this by +"temporarily" for individual calls to ``solve()``. We implement this by creating copies of the class's configuration for both specific instances -and for use by each `solve()` call: +and for use by each ``solve()`` call: .. doctest:: @@ -177,7 +177,7 @@ class will still create `c` instances that only have the single In addition to basic storage and retrieval, the Config system provides hooks to the argparse command-line argument parsing system. Individual Config entries can be declared as argparse arguments. To make -declaration simpler, the `declare` method returns the declared Config +declaration simpler, the :py:meth:`declare` method returns the declared Config object so that the argument declaration can be done inline: .. doctest:: @@ -261,8 +261,8 @@ class will still create `c` instances that only have the single It is frequently useful to know which values a user explicitly set, and which values a user explicitly set, but have never been retrieved. The configuration system provides two gemerator methods to return the items -that a user explicitly set (`user_values`) and the items that were set -but never retrieved (`unused_user_values`): +that a user explicitly set (:py:meth:`user_values`) and the items that +were set but never retrieved (:py:meth:`unused_user_values`): .. doctest:: @@ -277,11 +277,13 @@ class will still create `c` instances that only have the single ================================= Configuration objects support three methods for generating output and -documentation: `display()`, `generate_yaml_template()`, and -`generate_documentation()`. The simplest is `display()`, which prints -out the current values of the configuration object (and if it is a -container type, all of it's children). `generate_yaml_template` is -simular to `display`, but also includes the description fields as +documentation: :py:meth:`display()`, +:py:meth:`generate_yaml_template()`, and +:py:meth:`generate_documentation()`. The simplest is +:py:meth:`display()`, which prints out the current values of the +configuration object (and if it is a container type, all of it's +children). :py:meth:`generate_yaml_template` is simular to +:py:meth:`display`, but also includes the description fields as formatted comments. .. doctest::