Add the ability to autogenerate migrations. Because we need to support
different types of migration (expand and contract), this ends up being
significantly more complicated than what was needed in nova and cinder
and more akin to what was done in neutron. The key feature is here is
the use of an alembic hook called 'process_revision_directives', which
is called whenever one calls 'alembic revision --autogenerate'. We
extend this to allow us to hook into the autogeneration process and
ensure we only spit out directives for the relevant phase.
While we're here, we open up the Bobcat DB branch. This is similar to
what Neutron do (e.g. change I13ba740d245a46c41a969ff198e08ddff896eb1a).
Documentation will follow.
Change-Id: I17c9ff9508c5e2bd9521c18973af093d7550ab5a
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This is now folded into the initial migration of the 'expand_repo'
repository. Previously, this was a dummy migration. We simply move
things across and remove any code that was trying to work with the older
repo since it's no longer necessary.
A release note is added, even though it's not really necessary since
nothing will change for users. It's more of a heads up that things are
afoot.
Change-Id: I59882d88fe593ec1ae37415b2157584f7f3c85f8
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
With the new release of SQLAlchemy(1.4.27) TypeDecorator used
in common/sql/core.py file started failing (below error). I am not sure
if it is valid issue in SQLAlchemy or in our code base and we need to
blacklist the SQLAlchemy 1.4.27 version in requirements. But to unblock
the gate let's exclude it from sphinx-apidoc target.
Error:
Warning, treated as error:
/opt/stack/keystone/keystone/common/sql/core.py:docstring of keystone.common.sql.core.DateTimeInt.process_bind_param:19:undefined label: types_typedecorator
-https: //zuul.opendev.org/t/openstack/build/b2ee464fa1554cb89dc8873486865151
Change-Id: I7de055c2b266430bf886e200c3d8829a48ae9600
Switch to openstackdocstheme 2.2.1 and reno 3.1.0 versions. Using
these versions will allow especially:
* Linking from HTML to PDF document
* parallelizing building of documents
Update Sphinx version as well.
openstackdocstheme renames some variables, so follow the renames. A
couple of variables are also not needed anymore, remove them.
Set openstackdocs_auto_name to use project as name.
Set openstackdocs_pdf_link to link to PDF file.
Remove docs requirements from lower-constraints, they are not installed.
Change pygments_style to 'native' since old theme version always used
'native' and the theme now respects the setting and using 'sphinx' can
lead to some strange rendering.
See also
http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014971.html
Change-Id: I320a69816b4101bb76b88448881f3177c892ea92
This patch adds a new tox job/command for building the pdf
version of documentation.
tox -epdf-docs
In addition to adjusting the infra requirement for PDF build
support, the following changes are made to build a PDF doc
- Download link of config_options, sample config and policy
files are disabled for PDF doc as relative links do not
make sense.
- Pre-create the doc/build/pdf/_static directory as a
workaround because sphinx_feature_classification.support_matrix extension
is operating under the assumption that the _static directory already exist
and trying to copy support-matrix.css into it. We need to remove
this workaround once the problem in the support_matrix extension is fixed.
- Use the toctree_only=True workaround to avoid TOC duplicate links.
Change-Id: Ief8df5f6a5a22b8d0530458ac45f344a72cc3e49
Seems the user-guide no longer is a thing on its own, link to the
python-openstackclient documentation instead.
Change-Id: I84edd824e4b6a226e383071e9e3de1911f57939e
Some options are now automatically configured by the version 1.20:
- project
- html_last_updated_fmt
- latex_engine
- latex_elements
- version
- release.
Change-Id: Icca6ef602af26a1d10766fd416011cdcceaa00a1
- Fix minor grammatical issues
- Include the `strict_two_level` model in the enforcement model
section
- Improve readability
- Add enforcement examples in the form of diagrams
Change-Id: I483bf172dfe01f1db5a9673192eac988267996da
This reverts commit 485a6b2170.
With the release of Sphinx 2.1.1[1] constants are no longer autodoc'd so
we don't have this problem any more.
[1] https://github.com/sphinx-doc/sphinx/issues/6447
Change-Id: I8231f95e13ffad8f57ea6d7ae28216bfa27dc3d3
This reverts commit 698c20577e.
With the release of Sphinx 2.1.1[1] constants are no longer autodoc'd so
we don't have this problem any more.
[1] https://github.com/sphinx-doc/sphinx/issues/6447
Change-Id: Id9164a0311a59a78cb2b9018c95809d0fccc54f7
Since the 2.1.0 Sphinx release[1] module constants are now
autodocumented. Documenting the boilerplate CONF and LOG variables adds
unnecessary clutter to the docs, so add those constants to the ignore
list. This also adds a comment to the Sphinx configuration to explain
the situation.
[1] https://github.com/sphinx-doc/sphinx/issues/6447
Change-Id: If995b17feae6579479c796738ff8c290e550ab3f
Since the 2.1.0 release of Sphinx, the docs fail to build because of the
warnings-treated-as-errors of the now autodoc'd imported external
modules[1]. This change configures sphinx-autodoc to ignore those
constants so that the docs can build and the documentation from the
external modules isn't included in keystone's.
[1] https://github.com/sphinx-doc/sphinx/issues/6447
Change-Id: I7b1c2c740727446d5460dc0025e47e0e9b388d10
The code to generate a support matrix has been pulled into a common
library. Using this instead of duplicating code in various projects that
need it.
Change-Id: Ib15c086ceb84029e96be0fc60bd64f2a7a3e41aa
Co-Authored-By: Stephen Finucane <stephenfin@redhat.com>
Add an introduction to the federation documentation discussing
background information on identity federation and how it is implemented
in keystone.
This repurposes some of the content in this blog post[1] of which I am
the author.
[1] http://www.gazlene.net/demystifying-keystone-federation.html
Partial-bug: #1793374
Change-Id: I5f3a5e70c7b868762880930ea6277691f44c046a
This isn't actually used and is a leftover from a thing we did
seven years ago that survives today through copy-pasta.
Change-Id: I965ea16d39072dbf54a0d8d8718422efe9cff457
Added keystone-manage documentation from man pages
to the placeholder created for CLI Documentation.
Change-Id: I0e259c76d96c6479a6165c535bc49c032b2f41da
Since Sphinx 1.6 released, pbr's build_sphinx extension has been broken.
Specifically, pbr's [build_sphinx]/builders option is ignored. Luckily,
sphinx itself ipmlemented the feature but called it just 'builder'[1].
This patch fixes the config setting name and then cleans up a Sphinx
extension inclusion that is now automatically included.
[1] http://lists.openstack.org/pipermail/openstack-dev/2017-July/119396.html
Change-Id: I5da6a996ed442524ddb108a890df2d024ee07c4d
In a previous change [0] when warning-is-error was
added, the sphinx todo extension was causing errors
with duplicate registration.
However with the recent changes between pbr and
sphinx, this extension no longer throws a duplicate
error when using warning-is-error and we can add
it back in.
[0] https://review.openstack.org/#/c/439674/
Change-Id: Ie28d87dfca8ee5cbea28616b32c471d848c50759
There are auto generated configuration and policy guides which
were earlier manually copied and referenced. Used sphinext
module in oslo_config and oslo_policy to automatically render
those pages.
Change-Id: I2b49eb0083661cce70c5b9457fe5bd32dfe5e5e8
As part of the docs migration work[0] for Pike we need to switch to use
the openstackdocstheme.
[0]https://review.openstack.org/#/c/472275/
Change-Id: I31543b78a1b2d2df685e295d4d011c5e6e4a165b
Changed the existing keystone documenatation html theme to the
new openstackdocstheme. For reference, the same theme is being
used here, https://docs.openstack.org/admin-guide/.
Closes-Bug: #1692031
Change-Id: Ibf1b018e8ed38afa04d02ab033762d6b0ceab89b
etc/ is for config files that should be installed on disk to support a
running keystone. config-generator/ is for files that
oslo-config-generator uses to generate sample config files and are not
needed by keystone in a live deployment.
Change-Id: I0614709ded739d77ec620150bcb6c2f456024b6f
Since we're moving all policy into code and documenting it there we
should generate those docs automatically, so they are less likely to
be out-of-date.
Change-Id: If00cd3bcc654a45944c0bc8b3f146c75bd970f9a
partially-implements: blueprint policy-docs
1. The html_last_updated_fmt sphinx setting was providing a byte string
where sphinx expected a str, which produced warnings (and therefore
failures):
WARNING: The config value `html_last_updated_fmt' has type `bytes', expected to ['str'].
The solution provided is copied from cinder's solution[1].
2. The .keys() method in python 3 returns a dict_keys object rather than
a list and it does not include a .sort() method. This patch swaps
.sort() out for the global function sorted() which works in both python
2 and python 3.
This came up because on some newer distros that don't install python 2
by default, virtualenv defaults to creating a python 3 environment when
none is specified.
[1] https://review.openstack.org/#/c/433081
Change-Id: I68b796fa2e33fd6c3df67b542def31e6ba620944
This change removes the unused "warnerrors" setting that
was part of [pbr] which was replaced by "warning-is-error"
in sphinx 1.5 and above[0]. This also fixes any warnings
and errors that came up when running `tox -edocs` using
this new feature:
- Invalid code example highlighting
- Redundant loading of todo extension
[0] http://lists.openstack.org/pipermail/openstack-dev/2017-March/113085.html
Change-Id: I9a8789b448ffa199b4539f57e692bac251d75036
This introduces a feature support matrix to illustrate which of our
various token providers supports which API operations and features. This
is intended to mirror Nova's feature support matrix documentation page,
found here:
http://docs.openstack.org/developer/nova/support-matrix.html
After running `tox -e docs`, the result is embedded in
`doc/build/html/configuration.html`.
Change-Id: I3dc896a2906e25827a9e01afc7de5a737831c336
Currently, flake8 runs against doc related directories such as
releasenotes and api-ref. Might as well remove doc from the
flake8 exclude list. Each of these directories has only one
python file (conf.py).
Change-Id: I0445ad083d8d9167e0309950c200c9abb766bc1a
When building packages if git is absent, then we should not set
html_last_updated_fmt. It can still be set via the -D switch
when building with sphinx-build.
Change-Id: Iea0fb01314e1c4a66a55841df07b9bdaf10153a6
Closes-Bug: #1552251
Eventlet has been deprecated since the Kilo release and is
being removed in Newton.
A follow on patch will be proposed to remove the [ssl] section
since it is now redundant.
Co-Authored-By: Grzegorz Grasza <grzegorz.grasza@intel.com>
Partially implements: bp removed-as-of-newton
Change-Id: I963d94bbd188dbb6eba68623a42c5bc3f2289da4
os.popen() is deprecated since version 2.6. Resolved with use of
subprocess module.
Change-Id: Id8edeb60aa32f556b58ed0397d27598c39945241
Closes-Bug: #1529836
A temporary fix was added to get around a bug in how pbr handles
its autodoc_tree_index_modules setting. Since this bug is fixed we no
longer need the work around.
Change-Id: I6af0fdd6d1efacb47692b89c329e45ac59fef7cb
Closes-Bug: #1260495
The documenatation does not use intersphinx mappings so remove these so
as not to download them.
Related-Bug: #1353817
Change-Id: I0b0e48fa04d08b1023984b6d2169322060fcee9e
Since we are already using oslosphinx, there is no reason to
host our own version of the usual static files.
Change-Id: Id5a88a8bae17a6de3b10961f4db3314728588372
I think PEP 0263 (http://legacy.python.org/dev/peps/pep-0263/) is
not used anywhere else and so it should be removed when it's not
needed.
Change-Id: I7bbbf8ab0f47c6f8a3b25e92e4678e76c77f19a1
- Adds the ability to build docs using tox
- Fixes autodoc generation
A Sphinx extension is introduced in the commit to facilitate building
the API documentation. This extension should be removed when
bug 1260495 is fixed.
Change-Id: Ibf5e5403cb7d3e67947c87b2828b64a56a11fc30
Use the new oslo.sphinx version of the OpenStack doc
theme instead of copying it into this repo.
blueprint oslo.sphinx
Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>
Change-Id: I0bd91f7bb43f97b99051fed65b75fc05d5149cc8
Stephen Finucane