summaryrefslogtreecommitdiff
path: root/doc
Commit message (Collapse)AuthorAgeFilesLines
* remove unicode from codexuanyandong2021-04-161-1/+1
| | | | Change-Id: I062829a44a62014e88f285a82b6800e37f00ff28
* inherit from object is not required for py3Moisés Guimarães de Medeiros2021-01-122-2/+2
| | | | | Change-Id: I3f3b1dca78e2e9b2515231ccc6600b64f31039fb Signed-off-by: Moisés Guimarães de Medeiros <moguimar@redhat.com>
* Adding --check-defaults to validatorDavid Vallee Delisle2020-11-241-2/+154
| | | | | | | | | | | When troubleshooting, it's often interesting to see the deltas between the default or sample configs and the running configuration. The oslo_config.validator is a great tool to integrate this feature across all projects. It can also be easily captured by data collection tools like sosreports with the current deployment packages. Change-Id: I172d82f19a81282093b0d5f7ae4c1817801cd887 Signed-off-by: David Vallee Delisle <dvd@redhat.com>
* Adding pre-commitHervé Beraud2020-09-221-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Introduced changes: - pre-commit config and rules - Add pre-commit to pep8 gate, Flake8 is covered in the pre-commit hooks. - Applying fixes for pre-commit compliance in all code. Also commit hash will be used instead of version tags in pre-commit to prevend arbitrary code from running in developer's machines. pre-commit will be used to: - trailing whitespace; - Replaces or checks mixed line ending (mixed-line-ending); - Forbid files which have a UTF-8 byte-order marker (check-byte-order-marker); - Checks that non-binary executables have a proper shebang (check-executables-have-shebangs); - Check for files that contain merge conflict strings (check-merge-conflict); - Check for debugger imports and py37+ breakpoint() calls in python source (debug-statements); - Attempts to load all yaml files to verify syntax (check-yaml); - Run flake8 checks (flake8) (local) For further details about tests please refer to: https://github.com/pre-commit/pre-commit-hooks Change-Id: I65a40bbff17d92b959764846801d5e0ddd3b97ce Signed-off-by: Moisés Guimarães de Medeiros <moguimar@redhat.com>
* Fix pygments stylemelissaml2020-06-041-4/+4
| | | | | | | | New theme of docs respects pygments_style. more info: http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014971.html Change-Id: I88f448ac7fc7fb72187eb7bdad5bf19f327d8641
* docs: Mention other ways of escaping '$'Stephen Finucane2020-05-011-1/+1
| | | | | | | | | | | oslo config code treat treats the '$' as a special character and it needs to be delimited when using within a string. There are two ways of doing this, '$$' or '\$'. We document the former but not the latter. Fix this. Change-Id: I37cdf31ba1c2924779a46b1a2eeabb66c46a2212 Signed-off-by: Stephen Finucane <sfinucan@redhat.com> Closes-Bug: #1872839
* Add release notes links to doc indexHervé Beraud2020-04-161-0/+7
| | | | Change-Id: Ife6a9f6ff6116fda3bbb5b6a5987096f22b6f5a9
* Merge "Use stevedore to list the source drivers in documentation"8.0.2Zuul2020-03-093-0/+12
|\
| * Use stevedore to list the source drivers in documentationDoug Hellmann2019-12-173-0/+12
| | | | | | | | | | | | | | | | Add a section to the configuration guide to list all of the drivers using stevedore's sphinx integration. Change-Id: I6348f83efdd8a572821d2851ee4bd883f9e7e2b4 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* | [ussuri][goal] Drop python 2.7 support and testing8.0.0Stephen Finucane2020-02-031-2/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | OpenStack is dropping the py2.7 support in Ussuri cycle. Complete discussion & schedule can be found in - http://lists.openstack.org/pipermail/openstack-discuss/2019-October/010142.html - https://etherpad.openstack.org/p/drop-python2-support Ussuri Communtiy-wide goal: https://governance.openstack.org/tc/goals/selected/ussuri/drop-py27.html Change-Id: I13ce8e8264679a19c7b108381ccb969573ea9ac6 Signed-off-by: Stephen Finucane <sfinucan@redhat.com> Sem-Ver: api-break
* | Assume positional arguments are requiredDolph Mathews2017-03-301-0/+4
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | The 'positional' keyword specifically applies to oslo.config's argparse support. Unlike oslo.config, argparse assumes that all positional arguments are required by default, and you have to explicitly tell it that a positional argument is optional if you'd like to opt into that behavior. This patch adopts that same behavior for oslo.config. When you define an option to be non-positional (oslo.config's default, designed for config files), then oslo.config makes that option optional: However, when you define an option to be positional, oslo.config assumes that the option is primarily going to be used on the CLI and thus sets it as required, by default. This change in behavior has the side effect of allowing argparse to enforce required arguments on the CLI *while* parsing arguments, instead of depending on oslo.config to detect the condition *after* argparse has been allowed to parse "invalid" arguments. argparse correctly raises a SystemExit in this case, and prints the actual command usage and a "hey, you forgot this required argument", instead of allowing oslo.config to dump a backtrace to the CLI with a context-less error message ("context-less" in that no useful CLI usage information is dumped along with the crash to help you correct the condition). Change-Id: Ifdc6918444fe72f7e1649483c237cce64b4c72d8 Partial-Bug: 1676989
* tox: Keeping going with docscaoyuan2019-10-241-2/+2
| | | | | | | | | | | | Sphinx 1.8 introduced [1] the '--keep-going' argument which, as its name suggests, keeps the build running when it encounters non-fatal errors. This is exceptionally useful in avoiding a continuous edit-build loop when undertaking large doc reworks where multiple errors may be introduced. [1] https://github.com/sphinx-doc/sphinx/commit/e3483e9b045 Change-Id: Ied9f46640cf2f338a5784e1c72998f93b5c860c5
* Merge "Bump the openstackdocstheme extension to 1.20"Zuul2019-08-092-16/+1
|\
| * Bump the openstackdocstheme extension to 1.20pengyuesheng2019-08-012-16/+1
| | | | | | | | | | | | | | | | | | | | | | | | Some options are now automatically configured by the version 1.20: - project - html_last_updated_fmt - latex_engine - latex_elements - version - release. Change-Id: Iac913e9dea8318ad8398ed7478cb66d845fe7f1e
* | Blacklist sphinx 2.1.0 (autodoc bug)pengyuesheng2019-07-301-1/+1
|/ | | | | | See https://github.com/sphinx-doc/sphinx/issues/6440 for upstream details Change-Id: I4c4a2083d6578c625b948b1458412b832264f11e
* Merge "Add special handling for keystone_authtoken group"6.11.0Zuul2019-07-011-14/+22
|\
| * Add special handling for keystone_authtoken groupBen Nemec2019-05-221-14/+22
| | | | | | | | | | | | | | | | | | | | | | | | | | | | The keystone_authtoken options are created (not just registered) dynamically at runtime because of a need to not have a dependency on oslo.config in that library. As a result, there is no sane way to validate those options. This change adds a list of known problematic groups that we should ignore missing opts from. It also adds an info level log message that we are ignoring them so users know we can't confirm or deny the correctness of that piece of config. Change-Id: Ic2b36fe8be872d298a106c3f64905a5b935ced61
* | Switch to sphinxcontrib-apidocBen Nemec2019-06-1813-103/+16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Rather than have the API docs hand-curated and scattered throughout the documentation, let's use the apidoc module like all of the other Oslo projects so our API docs are consistent and easy to find. The documents that were exclusively API docs are removed entirely, and the ones where API docs were included with other content have been changed to reference the generated API docs rather than include them inline. The one exception is the drivers because they are in private modules that don't show up in the API docs. Those are still explicitly documented. Change-Id: I00bdd963e0d4f270c0d4b50c05f420317a137fd5
* | Merge "Add exclude-groups option to config validator"Zuul2019-06-031-0/+9
|\ \ | |/
| * Add exclude-groups option to config validatorBen Nemec2019-03-261-0/+9
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When dynamic groups are used, the sample config data may not know about those group names. As a result, validation of such files will always fail. This makes it hard to automate config checks since the output would need to be inspected manually to verify that the missing options are all from the dynamic group. Ideally, we would provide some way to map sample config groups to the dynamic group name used in the actual config, but that would be more complicated and still might not work in every case if a project doesn't include sample sections for a dynamic group (although they _should_ be doing so). Allowing certain group names to be excluded from validation lets us to solve this problem in a simple way and maintain validation of 99%[0] of the config options and enables the validation to be scripted since it won't need manual verification of the error output. Change-Id: I352fd48f86ecb876fe26a5e50e9a2633af1fff3d 0: citation needed ;-)
* | Cap Bandit below 1.6.0 and update Sphinx requirementBen Nemec2019-05-131-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | Bandit 1.6.0 accidentally changed how the exclusion list option is handled and breaks our use of it. Cap to the previous version until Bandit has fixed the problem. Sphinx 2.0 no longer works on python 2.7, so we need to start capping it there as well. Change-Id: Ib8da5b64084d5c9b7b7d896d6b7bb7844c0b9e90 Reference: https://github.com/PyCQA/bandit/pull/489
* | Add a Quick Start tutorialEric Fried2019-05-032-0/+79
| | | | | | | | | | | | | | | | | | | | As a user completely new to oslo_config (well, I had only experienced it in the already-implemented context of the nova project), I would like to have had a reference document that provided a step-by-step guide to writing a simple test script I could use to noodle around. It might have gone something like this. Change-Id: I02ff56f47ac8b93e0ee37eb55b53552059e4da27
* | Document precedence of config sourcesBen Nemec2019-04-232-1/+21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Previously the precedence details for the various sources oslo.config can consume were scattered around the developer documentation (for example in [0]). Since this is relevant for users too, we need to include it in the user-focused documentation. This collects all of the precedence information I am aware of and puts it on the documentation page for --config-file, --config-dir, and the sample source driver options. It also clarifies the file and dir precedence in the developer docs since previously that was only available in the API docstring. Change-Id: I41d8ac0f33ea60aea8ba5b150e53d7eafa323457 0: https://github.com/openstack/oslo.config/blob/0bc22839b09fcd7ae2de4f7fe5d63ac055fd0a78/oslo_config/cfg.py#L2095 Closes-Bug: 1825859
* | Move user docs to top of indexBen Nemec2019-04-221-1/+1
|/ | | | | | | | | The user-oriented docs for oslo.config were buried at the bottom of the index below a pile of developer docs. This made them difficult to find. Since we have far more users of oslo.config than we do developers using it we should prioritize the user docs. Change-Id: I602ee587e4acf1c1436b568906e316b78f104814
* Add note to docs about CLI opts and config filesBen Nemec2019-03-121-1/+5
| | | | | | | | | CLI opts can also be read from file, so once an option is registered for CLI use it doesn't need to be registered again to be usable in a config file. Add a note in the Registering Options section that explicitly explains this behavior. Change-Id: Ib75b5c314b96ec4c46f94e2847016a953433f480
* Revert "Optimizing the safety of the http link site in faq.rst."Jonathan Herlin2018-12-031-1/+1
| | | | | | | | This reverts commit 56377ae72a451a95f8707d5369eadaabd3f1932b. HTTPS is not used on lists.openstack.org Change-Id: I2d3f6e23e9a0249b30624326ca9134b559456dcc
* Optimizing the safety of the http link site in faq.rst.zhouxinyong2018-12-031-1/+1
| | | | Change-Id: Ice935e6f4e8dac0b8be2d58fead27029c08513b8
* Merge "Add support for looking in environment for config"Zuul2018-11-023-1/+8
|\
| * Add support for looking in environment for configChris Dent2018-10-173-1/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | An _environment source is added that looks in os.environ for values. Using the environment is on by default, but can be shut down by setting `use_env` to False when __call__ is called. The enviroment is inspected before any other sources of config data but the value is used after command line arguments and before config file options. This is done by checking both the command line and config files and then inspecting the location of the result. If it is command_line, we use it. If not, we use the environment value (if any). If there's no environment value, the config file value is used. If checking the command line and config file results in a KeyError, the environment value is used, if set. The names of the environment variables follow the rules described in oslo_config.sources._environment. A new exception has been added: ConfigSourceValueError, this is the superclass of the existing ConfigFileValueError. The code in _do_get has been updated to only use ConfigFileValueError when it is in fact a file from whence a ValueError came. Documentation has been updated and a rlease note created to indicate the new functionality. Change-Id: I3245c40ebdcc96f8e3b2dc0bab3b4aa71d07ad15
* | Merge "Add release note and documentation for config validator"Zuul2018-10-082-0/+64
|\ \ | |/ |/|
| * Add release note and documentation for config validatorBen Nemec2018-09-262-0/+64
| | | | | | | | Change-Id: Id23d7bbb38c6780621f09b2e24c0cc88831bdb1a
* | move some documentation out of the source filesDoug Hellmann2018-07-1911-16/+535
| | | | | | | | | | | | | | | | | | | | | | The cfg module is very large, and starts with a huge block of documentation. This patch moves that information into separate files in the reference section of the docs. A few formatting fixes need to be made to have it build cleanly, but the content is not changed in a substantive way. Change-Id: I86aa90bbf180b5dc9acbcedb024e5361d49954c3 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* | Merge "User guide documentation for backend drivers for oslo.config"Zuul2018-07-162-0/+13
|\ \
| * | User guide documentation for backend drivers for oslo.configRaildo Mascena2018-07-052-0/+13
| |/ | | | | | | | | | | | | | | | | New documentation sections explaning how to use the backend drivers for oslo.config, also include explanation on how to use the remote_file driver. Change-Id: I45fc2155f6fe2d8bee058dac880afba8bb9bfd53 Blueprint: oslo-config-drivers
* | move configuration option list to the configuration guideDoug Hellmann2018-06-284-8/+8
| | | | | | | | | | | | | | | | | | | | | | We have a section in the reference guide showing the configuration options built into oslo.config. Move that to the configuration guide instead so it is linked from the Configuration Guide list at https://docs.openstack.org/$series/configuration/ like the similar documentation for other libraries. Change-Id: I7da159cfaa643c2cc094f6fb1c0aeaa956f3eb77 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* | improve the documentation for option location informationDoug Hellmann2018-06-131-1/+1
|/ | | | | | | | | | | Fix an error in the example code by setting loc to the Location enum value instead of the LocationInfo tuple. Add a cross-reference from the ConfigOpts get_location() method to the more extensive reference documentation about option locations. Change-Id: Ic9850afd78a7b42f4e807b04e78729a674942e15 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* Remove boolean from StrOpt exampleBen Nemec2018-04-241-3/+0
| | | | | | | I'm not sure why this was here, but it doesn't make sense since we're documenting StrOpts in this section. Change-Id: I74c73c8088ec266d1f827bc51b4d78fc7be48a38
* use environment variable to control file location probingDoug Hellmann2018-04-181-0/+17
| | | | | | | | | If OSLO_CONFIG_SHOW_CODE_LOCATIONS is set to any non-empty string it will turn on the ability to see which file has the definition of an Opt or where set_default() was invoked. Change-Id: Ie705014dcf331e3c6b3367d2fefbfb9acc091799 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* Merge "Follow the new PTI for document build"Zuul2018-03-221-0/+9
|\
| * Follow the new PTI for document buildSean McGinnis2018-03-211-0/+9
| | | | | | | | | | | | | | | | | | | | | | | | For compliance with the Project Testing Interface as described in: https://governance.openstack.org/tc/reference/project-testing-interface.html For more detials information, please refer to: http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html Change-Id: I46a861f88166b3b2de0a532cc88beef1ef91ab89
* | Remove MultiConfigParserBen Nemec2018-03-211-3/+0
|/ | | | | | | | | | | | | | This has been deprecated for quite a while and some of the upcoming work to be done in oslo.config will be easier if we don't have to deal with this unused parser too. The class is still currently in use in networking-cisco, but in change https://review.openstack.org/554617 we have provided a fix that removes their reliance on it. They are planning to remove it entirely in Rocky and are only testing against a capped version in Queens so we are not going to wait on them. Change-Id: Id6ae40311f967e172e45bcb0e61812365a72618b
* add user documentation for get_location()Doug Hellmann2018-03-152-1/+66
| | | | | Change-Id: I35ef216552b0b8def9c70b262825acb4a50083f4 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* Fix the invalid links for doc file in oslo.configshangxiaobj2017-12-281-2/+2
| | | | | | | Replace the invalid links with the right ones for the document according to the newest Openstack website. Change-Id: Id94551a864710231a9d9d23d8632a86439cd61bd
* Remove redundant colon in doc4.12.0Yaguo Zhou2017-08-291-1/+1
| | | | | | | ".. code-block:: shell" appears in the generated doc html by mistake because of the redundant colon in the doc source Change-Id: I5c54fd48a7705cb7d84016707a4bb51e8dd79b2a
* doc: Specify openstackdocs theme4.8.0Akihiro Motoki2017-07-081-3/+1
| | | | Change-Id: If3e04107bc2c4bb4c152e79650f8be870bf4721f
* switch from oslosphinx to openstackdocsthemeDoug Hellmann2017-06-291-11/+12
| | | | | | Change-Id: I13211d11ae96a8bbc5f8bbb958473dbcf6e4c844 Depends-On: Ifc5512c0e2373cf3387e0e0498268eab092e52bb Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* import content from the configuration reference guideDoug Hellmann2017-06-294-0/+230
| | | | | | | This information used to be in openstack-manuals/doc/config-reference. Change-Id: I219dee590a706924978ce8d2a2c151a6ae51c8b6 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* rearrange docs based on new standard layoutDoug Hellmann2017-06-2721-22/+43
| | | | | | Change-Id: I5a86fc144c628772c750e8626d0728e3782ea469 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
* Fix html_last_updated_fmt for Python3loooosy2017-06-131-2/+1
| | | | | | | | | | | | | | | | | html_last_updated_fmt option is interpreted as a byte string in python3, causing Sphinx build to break. This patch makes it utf-8 string. Changing Popen to .check_output because of 3 reasons: 1. check_output() will raise CalledProcessError if the called process returns a non-zero return code. 2. For consistency with keystone [1] and cinder [2] 3. It makes the code look much better. [1] https://review.openstack.org/#/c/457142/ [2] https://review.openstack.org/#/c/433081 Change-Id: I8872866338d93bc8328391537198df6c7981859f
* Rework the 'oslo-config-generator' documentation4.4.0Stephen Finucane2017-06-071-71/+245
| | | | | | | | | There's a lot of shuffling docs around, but the main point is to document the application parameters and the support for multiple output formats recently added. Change-Id: I26827801df917619d4256ef4c718051f5c395a29 Implements: bp machine-readable-sample-config
View Lorry Controller Status