diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/requirements.txt | 4 | ||||
| -rw-r--r-- | doc/source/cli/generator.rst | 11 | ||||
| -rw-r--r-- | doc/source/conf.py | 9 | ||||
| -rw-r--r-- | doc/source/configuration/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/configuration/options.rst | 17 | ||||
| -rw-r--r-- | doc/source/configuration/quickstart.rst | 78 | ||||
| -rw-r--r-- | doc/source/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/cfgfilter.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/configopts.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/configuration-files.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/drivers.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/exceptions.rst | 20 | ||||
| -rw-r--r-- | doc/source/reference/fixture.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/helpers.rst | 5 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/opts.rst | 25 | ||||
| -rw-r--r-- | doc/source/reference/parser.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/types.rst | 6 |
18 files changed, 119 insertions, 106 deletions
diff --git a/doc/requirements.txt b/doc/requirements.txt index 2980a2d..5f4e8e2 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,7 +2,9 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD +sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD +sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD +sphinxcontrib-apidoc>=0.2.0 # BSD openstackdocstheme>=1.18.1 # Apache-2.0 reno>=2.5.0 # Apache-2.0 fixtures>=3.0.0 # Apache-2.0/BSD diff --git a/doc/source/cli/generator.rst b/doc/source/cli/generator.rst index cada142..99e3bd7 100644 --- a/doc/source/cli/generator.rst +++ b/doc/source/cli/generator.rst @@ -289,7 +289,7 @@ where the top-level keys are: the ``OptGroup`` they are assigned to which defaults to ``DEFAULT`` if unset. For information on the various attributes of each option, refer to - :ref:`option-definitions`. + :class:`oslo_config.cfg.Opt` and its subclasses. ``deprecated_options`` @@ -358,12 +358,3 @@ facilitate this, options can be supplied with a ``sample_default`` attribute: cfg.StrOpt('base_dir' default=os.getcwd(), sample_default='/usr/lib/myapp') - -API ---- - -.. currentmodule:: oslo_config.generator - -.. autofunction:: main -.. autofunction:: generate -.. autofunction:: register_cli_opts diff --git a/doc/source/conf.py b/doc/source/conf.py index ec59f02..52ac17b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -13,6 +13,7 @@ extensions = [ 'openstackdocstheme', 'oslo_config.sphinxconfiggen', 'oslo_config.sphinxext', + 'sphinxcontrib.apidoc', ] # openstackdocstheme options @@ -75,3 +76,11 @@ latex_documents = [ '%s Documentation' % project, 'OpenStack Foundation', 'manual'), ] + +# -- sphinxcontrib.apidoc configuration -------------------------------------- + +apidoc_module_dir = '../../oslo_config' +apidoc_output_dir = 'reference/api' +apidoc_excluded_paths = [ + 'tests', +] diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 4858bd5..7dfa30e 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -5,6 +5,7 @@ .. toctree:: :maxdepth: 2 + quickstart format mutable options diff --git a/doc/source/configuration/options.rst b/doc/source/configuration/options.rst index 53173f3..0800936 100644 --- a/doc/source/configuration/options.rst +++ b/doc/source/configuration/options.rst @@ -2,6 +2,23 @@ Configuration Options from oslo.config ======================================== +When loading values from the sources defined by the following options, the +precedence is as follows: + +#. Command Line +#. Environment Variables +#. Config Files from ``--config-dir`` [1]_ +#. Config Files from ``--config-file`` +#. Pluggable Config Sources + +If a value is specified in multiple locations, the location used will be the +one higher in the list. For example, if a value is specified both on the +command line and in an environment variable, the value from the command line +will be the one returned. + +.. [1] Files in a config dir are parsed in alphabetical order. Later files + take precedence over earlier ones. + .. show-options:: oslo.config diff --git a/doc/source/configuration/quickstart.rst b/doc/source/configuration/quickstart.rst new file mode 100644 index 0000000..21fc722 --- /dev/null +++ b/doc/source/configuration/quickstart.rst @@ -0,0 +1,78 @@ +========================== + oslo.config Quick Start! +========================== + +Are you brand new to oslo.config? This brief tutorial will get you started +understanding some of the fundamentals. + +Prerequisites +------------- +* A plain text editor or Python-enabled IDE +* A Python interpreter +* A command shell from which the interpreter can be invoked +* The oslo_config library in your Python path. + +Test Script +----------- +Put this in a file called ``oslocfgtest.py``. + +.. code:: python + + # The sys module lets you get at the command line arguments. + import sys + + # Load up the cfg module, which contains all the classes and methods + # you'll need. + from oslo_config import cfg + + # Define an option group + grp = cfg.OptGroup('mygroup') + + # Define a couple of options + opts = [cfg.StrOpt('option1'), + cfg.IntOpt('option2', default=42)] + + # Register your config group + cfg.CONF.register_group(grp) + + # Register your options within the config group + cfg.CONF.register_opts(opts, group=grp) + + # Process command line arguments. The arguments tell CONF where to + # find your config file, which it loads and parses to populate itself. + cfg.CONF(sys.argv[1:]) + + # Now you can access the values from the config file as + # CONF.<group>.<opt> + print("The value of option1 is %s" % cfg.CONF.mygroup.option1) + print("The value of option2 is %d" % cfg.CONF.mygroup.option2) + +Conf File +--------- +Put this in a file called ``oslocfgtest.conf`` in the same directory as +``oslocfgtest.py``. + +.. code:: ini + + [mygroup] + option1 = foo + # Comment out option2 to test the default value + # option2 = 123 + +Run It! +------- +From your command shell, in the same directory as your script and conf, invoke: + +.. code:: shell + + python oslocfgtest.py --config-file oslocfgtest.conf + +Revel in the output being exactly as expected. If you've done everything +right, you should see: + +.. code:: shell + + The value of option1 is foo + The value of option2 is 42 + +Now go play with some more advanced option settings! diff --git a/doc/source/index.rst b/doc/source/index.rst index 38aba21..af24458 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,9 +11,9 @@ Contents .. toctree:: :maxdepth: 2 + configuration/index reference/index cli/index - configuration/index contributor/index Indices and tables diff --git a/doc/source/reference/cfgfilter.rst b/doc/source/reference/cfgfilter.rst deleted file mode 100644 index c11cddd..0000000 --- a/doc/source/reference/cfgfilter.rst +++ /dev/null @@ -1,5 +0,0 @@ --------------------- -The cfgfilter Module --------------------- - -.. automodule:: oslo_config.cfgfilter diff --git a/doc/source/reference/configopts.rst b/doc/source/reference/configopts.rst deleted file mode 100644 index 06c9c3b..0000000 --- a/doc/source/reference/configopts.rst +++ /dev/null @@ -1,8 +0,0 @@ --------------------- -The ConfigOpts Class --------------------- - -.. currentmodule:: oslo_config.cfg - -.. autoclass:: ConfigOpts - :members: diff --git a/doc/source/reference/configuration-files.rst b/doc/source/reference/configuration-files.rst index 7544749..b4e299d 100644 --- a/doc/source/reference/configuration-files.rst +++ b/doc/source/reference/configuration-files.rst @@ -42,7 +42,10 @@ option name) can appear many times, in config files or on the command line. Later values always override earlier ones. The order of configuration files inside the same configuration directory is -defined by the alphabetic sorting order of their file names. +defined by the alphabetic sorting order of their file names. Files in a +configuration directory are parsed after any individual configuration files, +so values that appear in both a configuration file and configuration directory +will use the value from the directory. The parsing of CLI args and config files is initiated by invoking the config manager for example: diff --git a/doc/source/reference/drivers.rst b/doc/source/reference/drivers.rst index 0c06ab1..91807c6 100644 --- a/doc/source/reference/drivers.rst +++ b/doc/source/reference/drivers.rst @@ -3,11 +3,14 @@ Backend Drivers --------------- -.. automodule:: oslo_config.sources +Refer to :py:mod:`oslo_config.sources` Known Backend Drivers --------------------- +.. NOTE(bnemec): These are private modules, so we need to explicitly + document them + .. automodule:: oslo_config.sources._uri .. automodule:: oslo_config.sources._environment diff --git a/doc/source/reference/exceptions.rst b/doc/source/reference/exceptions.rst deleted file mode 100644 index 8036b84..0000000 --- a/doc/source/reference/exceptions.rst +++ /dev/null @@ -1,20 +0,0 @@ ----------- -Exceptions ----------- - -.. currentmodule:: oslo_config.cfg - -.. autoexception:: Error -.. autoexception:: NotInitializedError -.. autoexception:: ArgsAlreadyParsedError -.. autoexception:: NoSuchOptError -.. autoexception:: NoSuchGroupError -.. autoexception:: DuplicateOptError -.. autoexception:: RequiredOptError -.. autoexception:: TemplateSubstitutionError -.. autoexception:: ConfigFilesNotFoundError -.. autoexception:: ConfigFilesPermissionDeniedError -.. autoexception:: ConfigDirNotFoundError -.. autoexception:: ConfigFileParseError -.. autoexception:: ConfigFileValueError -.. autoexception:: DefaultValueError diff --git a/doc/source/reference/fixture.rst b/doc/source/reference/fixture.rst deleted file mode 100644 index 47c4939..0000000 --- a/doc/source/reference/fixture.rst +++ /dev/null @@ -1,8 +0,0 @@ ------------- -Test Fixture ------------- - -.. currentmodule:: oslo_config.fixture - -.. autoclass:: Config - :members: diff --git a/doc/source/reference/helpers.rst b/doc/source/reference/helpers.rst index 4a36dc8..e9ee18a 100644 --- a/doc/source/reference/helpers.rst +++ b/doc/source/reference/helpers.rst @@ -2,11 +2,6 @@ Helper Functions ---------------- -.. currentmodule:: oslo_config.cfg - -.. autofunction:: find_config_files -.. autofunction:: set_defaults - Showing detailed locations for configuration settings ----------------------------------------------------- diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 3a6290d..a4593f8 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -5,6 +5,7 @@ .. toctree:: :maxdepth: 2 + API <api/modules> defining naming accessing @@ -12,14 +13,7 @@ command-line deprecating globals - opts - types - configopts - cfgfilter helpers - fixture - parser - exceptions styleguide mutable locations diff --git a/doc/source/reference/opts.rst b/doc/source/reference/opts.rst deleted file mode 100644 index b7532ed..0000000 --- a/doc/source/reference/opts.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _option-definitions: - -==================== - Opt and Subclasses -==================== - -.. currentmodule:: oslo_config.cfg - -.. autoclass:: Opt -.. autoclass:: StrOpt -.. autoclass:: BoolOpt -.. autoclass:: IntOpt -.. autoclass:: FloatOpt -.. autoclass:: ListOpt -.. autoclass:: DictOpt -.. autoclass:: MultiOpt -.. autoclass:: MultiStrOpt -.. autoclass:: IPOpt -.. autoclass:: PortOpt -.. autoclass:: HostnameOpt -.. autoclass:: HostAddressOpt -.. autoclass:: URIOpt -.. autoclass:: DeprecatedOpt -.. autoclass:: SubCommandOpt -.. autoclass:: OptGroup diff --git a/doc/source/reference/parser.rst b/doc/source/reference/parser.rst deleted file mode 100644 index 2d9430f..0000000 --- a/doc/source/reference/parser.rst +++ /dev/null @@ -1,8 +0,0 @@ ------------- -File Parsing ------------- - -.. autoclass:: oslo_config.iniparser.BaseParser - -.. autoclass:: oslo_config.cfg.ConfigParser - :members: parse diff --git a/doc/source/reference/types.rst b/doc/source/reference/types.rst deleted file mode 100644 index 848d75d..0000000 --- a/doc/source/reference/types.rst +++ /dev/null @@ -1,6 +0,0 @@ -============================= - Option Types and Validation -============================= - -.. automodule:: oslo_config.types - :members: |