From de44226faedf3c06ff50579a49a39f173f5010b0 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 15 Oct 2015 11:55:04 +0200 Subject: [PATCH] Use versionadded and versionchanged in doc Document in which version new types and functions were added using ".. versionadded:: x.y". Document changes using ".. versionchanged:: x.y." When a whole module was added in a version, use the versionadded tag in the module top docstring, not on each type/function. I used "git blame" + "git tag --contains=SHA1" to find these version, and then I checked manually each version. Change-Id: Ieb8b3cbb1cb71a98cb714c410635b5c45f1afb08 --- doc/source/generator.rst | 2 ++ oslo_config/cfg.py | 28 ++++++++++++++++++++++++++++ oslo_config/cfgfilter.py | 9 ++++++--- oslo_config/generator.py | 1 + oslo_config/types.py | 10 ++++++++++ 5 files changed, 47 insertions(+), 3 deletions(-) diff --git a/doc/source/generator.rst b/doc/source/generator.rst index ea577ee8..aab05b09 100644 --- a/doc/source/generator.rst +++ b/doc/source/generator.rst @@ -16,6 +16,8 @@ namespaces:: $> oslo-config-generator --namespace myapp --namespace oslo.messaging > myapp.conf +.. versionadded:: 1.4 + Defining Option Discovery Entry Points -------------------------------------- diff --git a/oslo_config/cfg.py b/oslo_config/cfg.py index ef17dc16..d2ce1286 100644 --- a/oslo_config/cfg.py +++ b/oslo_config/cfg.py @@ -674,6 +674,15 @@ class Opt(object): a string explaining how the option's value is used + .. versionchanged:: 1.2 + Added *deprecated_opts* parameter. + + .. versionchanged:: 1.4 + Added *sample_default* parameter. + + .. versionchanged:: 1.9 + Added *deprecated_for_removal* parameter. + .. versionchanged:: 2.7 An exception is now raised if the default value has the wrong type. @@ -953,6 +962,8 @@ class DeprecatedOpt(object): Then the value of "[group1]/opt1" will be ['val11', 'val12', 'val21', 'val22']. + + .. versionadded:: 1.2 """ def __init__(self, name, group=None): @@ -1051,6 +1062,10 @@ class IntOpt(Opt): Option with ``type`` :class:`oslo_config.types.Integer` `Kept for backward-compatibility with options not using Opt directly`. + + .. versionchanged:: 1.15 + + Added *min* and *max* parameters. """ def __init__(self, name, min=None, max=None, **kwargs): @@ -1078,6 +1093,9 @@ class ListOpt(Opt): Option with ``type`` :class:`oslo_config.types.List` `Kept for backward-compatibility with options not using Opt directly`. + + .. versionchanged:: 2.5 + Added *item_type* and *bounds* parameters. """ def __init__(self, name, item_type=None, bounds=None, **kwargs): @@ -1094,6 +1112,8 @@ class DictOpt(Opt): Option with ``type`` :class:`oslo_config.types.Dict` `Kept for backward-compatibility with options not using Opt directly`. + + .. versionadded:: 1.2 """ def __init__(self, name, **kwargs): @@ -1108,6 +1128,8 @@ class IPOpt(Opt): :param version: one of either ``4``, ``6``, or ``None`` to specify either version. + + .. versionadded:: 1.4 """ def __init__(self, name, version=None, **kwargs): @@ -1147,6 +1169,8 @@ class MultiOpt(Opt): The command line ``--foo=1 --foo=2`` would result in ``cfg.CONF.foo`` containing ``[1,2]`` + + .. versionadded:: 1.3 """ multi = True @@ -1249,6 +1273,8 @@ class _ConfigFileOpt(Opt): This allows us to properly handle the precedence of --config-file options over previous command line arguments, but not over subsequent arguments. + + .. versionadded:: 1.2 """ class ConfigFileAction(argparse.Action): @@ -1295,6 +1321,8 @@ class _ConfigDirOpt(Opt): _Namespace object. This allows us to properly handle the precedence of --config-dir options over previous command line arguments, but not over subsequent arguments. + + .. versionadded:: 1.2 """ class ConfigDirAction(argparse.Action): diff --git a/oslo_config/cfgfilter.py b/oslo_config/cfgfilter.py index 4b00166a..77c77758 100644 --- a/oslo_config/cfgfilter.py +++ b/oslo_config/cfgfilter.py @@ -24,6 +24,8 @@ There are three use cases for the ConfigFilter class: 3. Limit the options on a Cfg object that can be accessed. +.. versionadded:: 1.4 + Cross-Module Option Dependencies -------------------------------- @@ -121,8 +123,6 @@ we can expose options such that only those options are present:: print(restricted_conf.foo) print(restricted_conf.bar) # raises NoSuchOptError - - """ import collections @@ -132,7 +132,10 @@ from oslo_config import cfg class CliOptRegisteredError(cfg.Error): - """Raised when registering cli opt not in original ConfigOpts.""" + """Raised when registering cli opt not in original ConfigOpts. + + .. versionadded:: 1.12 + """ def __str__(self): ret = "Cannot register a cli option that was not present in the" \ diff --git a/oslo_config/generator.py b/oslo_config/generator.py index 5090d12e..6c391ffd 100644 --- a/oslo_config/generator.py +++ b/oslo_config/generator.py @@ -20,6 +20,7 @@ Tool for generating a sample configuration file. See ../doc/source/generator.rst for details. +.. versionadded:: 1.4 """ import logging diff --git a/oslo_config/types.py b/oslo_config/types.py index 99f42f39..69843f15 100644 --- a/oslo_config/types.py +++ b/oslo_config/types.py @@ -17,6 +17,7 @@ Use these classes as values for the `type` argument to :class:`oslo_config.cfg.Opt` and its subclasses. +.. versionadded:: 1.3 """ import re @@ -51,6 +52,12 @@ class String(ConfigType): :param ignore_case: If True case differences (uppercase vs. lowercase) between 'choices' or 'regex' will be ignored; defaults to False. + + .. versionchanged:: 2.1 + Added *regex* parameter. + + .. versionchanged:: 2.5 + Added *ignore_case* parameter. """ BASE_TYPES = six.string_types @@ -170,6 +177,9 @@ class Integer(ConfigType): :param min: Optional check that value is greater than or equal to min :param max: Optional check that value is less than or equal to max + + .. versionchanged:: 2.4 + The class now honors zero for *min* and *max* parameters. """ BASE_TYPES = six.integer_types