Providing a sample policy file is all well and good, but it's not
exactly designed for readability on the web. Make use of the 'sphinxext'
module built into oslo.policy to do this.
Change-Id: I6cceeca7edcacb762daa1f22f2138e2d2334b3a2
Providing a sample configuration file is all well and good, but it's not
exactly designed for readability on the web. Make use of the 'sphinxext'
module built into oslo.config to do this.
Change-Id: I75e8f0adae7cfaaa6020870cdb20dc2144fc70eb
This adds a fresh cellsv2 overview document that talks about
deployment decisions for single and multiple cell environments
in an attempt to help address confusion about what the service
layouts look like in a multi-cell setup.
Change-Id: I1da7c375dbb98c125aebabec548280de8d8ed381
Per the spec [1]:
user/ – end-user content such as concept guides, advice, tutorials,
step-by-step instructions for using the CLI to perform specific tasks,
etc.
The remaining content all ends up in here.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: I480eee9cd7568efe2f76dd185004774588eb4a99
Per the spec [1]:
reference/ – any reference information associated with a project that
is not covered by one of the above categories. Library projects should
place their automatically generated class documentation here.
There are a couple of documents that focus on nova internals, but won't
necessarily be applicable to user. These are moved here.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: I94614c2383329e1fbed60d9c5aca3fab5170ef8f
Per the spec [1]:
contributor/ – anything related to contributing to the project or how
the team is managed. Applies to some of the current content under
/developer, we are changing the name to emphasize that not all
contributors are developers and sometimes developers are users but not
contributors.
We currently have a handful of docs that focus on the "how to develop or
contribute" aspects of nova, and these are moved. Docs that focus on
architecture or design decisions for nova are not moved, as these will
go into 'reference'.
A TODO is added to the former 'api_plugins' document as it's mega
out-of-date and needs some serious work.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: Iad770688b4eafeb9caa710b4398b02d80a017a70
Per the spec [1]:
configuration/ – automatically generated configuration reference
information based on oslo.config’s sphinx integration (or manually
written for projects not using oslo.config). Step-by-step guides for
doing things like enabling cells or configuring a specific driver
should be placed in the admin/ section.
Only the 'sample_policy' and 'sample_config' files fit into this
category at present. We may wish to add files that use the oslo.config
and oslo.policy Sphinx integrations, but that can come later.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: I587551ada1932876bca51a362f8dfeef6f7dd70b
Per the spec [1]:
cli/ – command line tool reference docs, similar to man pages These
may be automatically generated with cliff's sphinx integration, or
manually written when auto-generation is not possible.
All of the docs currently found in 'man' fit that category, so those and
those alone are moved. It'll be a great day in the parish when we can
replace all of these with cliff's Sphinx integration.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: I45bed324ec37cfea7c1a574ec06af38e7b875a1c
This provides a brief explanation of the new nova-api-wsgi [1] and
nova-metadata-wsgi [2] scripts in the Architecture section of the devref
with links to the new doc added to the man pages for the eventlet
scripts.
The nova-api.rst mentioned ec2 so figured best to fix that now
rather than forget about it, despite not being entirely germane.
There is also a reno note that indicates the availability of the new
scripts.
There is a devstack change which is testing the new wsgi scripts as
well as forcing grenade to not use them at
If2d7e363a6541854f2e30c03171bef7a41aff745
[1] I7c4acfaa6c50ac0e4d6de69eb62ec5bbad72ff85
[2] Icb35fe2b94ab02c0ba8ba8129ae18aae0f794756
Change-Id: I351b2af3b256d3031bd2a65feba0495e815f8427
Related-Bug: #1661360
This was previously hidden within the code review guide making it almost
impossible to find from the initial index page.
Change-Id: I47e771c641d72a837345b1b9a07e86ca4313b518
There are always some questions about how quotas work
in Nova, particularly how they are checked against
the configuration vs the 'default' quota class in the
database, and global vs project-specific quotas.
This change starts a document on quotas a high-level.
It does not get into the lower-level details of how
quotas work or are designed in Nova, or the issues
that can arise with the existing quota system or future
plans.
Change-Id: Iabe3d40f44c59f14fa89ceddc556497d2885845c
Turns out you can't embed a comment inside a toctree, resulting in the
following error:
WARNING: toctree contains reference to nonexisting document u'.. NOTE:
keep this list sorted by title'
Change-Id: Ifc3fbcde8371b8002f3b17364e6f252e36113702
This document describes the steps to test zero downtime
upgrade process.
Change-Id: Ieafd65da959f6153524f1f3ab0522025b94cbef4
Co-Authored-by: Anusha Unnam <anusha.unnam@intel.com>
The unsorted nature of this has always annoyed me, and since
I'm going to add a new item to the list in a following change
let's sort the list. Note that the list is sorted by title
in the linked doc, not the name of the doc file itself.
Change-Id: I24671fe5256889c3abc1ba36d70a450213f20234
placement_dev.rst provides a nova-developer oriented perspective on
the placement API including some explanation of its structure, some
gotchas to be aware of, and some instruction on how to add to it.
Subsequent patches will fill in the missing sections.
Change-Id: Ia571800774aa14beab121c85a693d75fc30ed517
This is the initial set of docs for the placement API
service introduced in the Newton release.
We still have to flesh out the API reference in detail
but this gets us started.
The deployment steps are taken from how devstack does
this today.
Change-Id: Ic2436d92a7cefaeb1ae67ed878da968444f2f18d
Adding a reminder that V2 APIs should no longer be used and are only
available for backward compatibility purposes.
Change-Id: Ib885c102a59b3c339b0e7986145a1c2defb346fc
Closes-bug: 1580552
During the defcore discussion about the fact that the extensions
facility was deleted from Nova, folks pointed to this doc and the word
extensions to state that it was clearly still supported. There are
many levels of confusion there.
This tries to crisp up the introduction and links to the API docs for
Nova.
Change-Id: Ic0be29fb14bfb00ed7691439318325967d138dc9
This disables the generation of the raw module api documentation in
our docs target. It is mostly not useful, as it builds a giant tree of
module documentation that are 98% boiler plate lists of methods with
no real content.
We leave the sphinx.ext.autodoc in the conf, which allows you to
specifically pull in modules for documentation when you want
to. doc/source/services.rst is an example of doing this in tree, which
still works after this change.
Change-Id: I4c10a8e45756cdcf612faca574e2fb3b7ffa2bdb
This emits a warning message when hooks are used to ensure that admins
understand that this facility is deprecated in Nova going forward. It
also removes the links to the meager documentation on hooks to ensure
no one finds these by accident and starts using them. Also add a
comment to the code file itself incase someone ends up in it from
other searches.
Change-Id: I31b1223a0dc3fdffe356a816b591fdd88a31483a
Basic conversion done with pandoc then I had to fix some links and the
title underlines.
The Mentoring page has been merged into the (mostly empty) "How to get
(more) involved with Nova" page.
Change-Id: Ib4a11b21c0fd6aaf86e643897193f59cefb626c4
This effort is trying to ensure we better document what is currently
tested and know to work, and what is not currently tested.
This renames the Hypervisor support matrix, to the Feature support matrix.
The vision is to move the support matrix ticks to appear only for
features that have tests passing. To enable this to happen, the column
will change from being the virt driver, to being a specific combination
of technologies (such as libvirt + KVM + ceph + neutron ML2 with ovs)
The second step is to include information about the maturity of the
specific feature that is being tested. This will mean the matrix rows
will instead reference a feature group, that has an associated list of
tempest test uuid and links to detailed API docs.
Change-Id: Ia2d489cb4e1fd57737468df4f9fc10e9ad8c011c
Uses openstackdocstheme to match other content
Has a dependent change in project-config also so that
file will build to developer.openstack.org/compute
at https://review.openstack.org/#/c/231000/
Change-Id: Ic060a1e79e4b2f8695cb788ff4df018e0cfd3286
The scheduler evolution has been a priority for both kilo and liberty.
This document attempts to describe the general direction of that effort.
The goal for this work is to make it easier for others to help with this
effort, and make sure we agree the current direction.
Change-Id: I8746362b6a596690de21de34599462a6e27a92da
This adds a document that aims to provide a checklist-like review
guideline for code reviewers. We can encode small decisions and tribal
knowledge in this document to help increase consistency.
Right now, this just adds upgrade-related review items as those are
some of the more complicated and least-documented at the moment.
Change-Id: I5bbb7e4e2192b853373fed38ca0ad873fc8b329e
This commit adds sample config file generation to the nova devref
using the oslo.config sphinxconfiggen module which was recently added.
This will generate a new sample config each time build sphinx is run.
This is then used on a new docs page where you can either view the file
in its entirety, or download the file. The sphinx module was added in
the oslo.config 2.3.0 release.
Change-Id: I6d9150d81c8204bee8f775021a854928671bdd02
In addition to being a database proxy and object backporter the
conductor also manages rebuild, resize/migrate, and building instances.
This documents why that is done.
Change-Id: Ieb9134302d21a11fe9b9ee876bb7b0dd32b437e1
Whenever someone asks about v2 vs v2.1 vs v3 API and I point
to the docs, I also point to the Liberty summit session which
is good for new people to watch before trying to sort through
the docs and code, so add a link to the high-level section
of the docs.
Change-Id: I34d734454afcfdae3f874160dfd11662e61c2faa
The docs had references to https://docs.openstack.org but this
website is http only. Connecting to the https address results in
an unable to connect error.
Replacing with http also makes it consistent with all other references
to docs.openstack.org.
Change-Id: I5367bb623aff33148cceadbdcb8df3550f655ed4
Commit bd7e62f796 disabled the
autodoc_index_modules flag for building docs but it wasn't really
necessary, that change was just to get the module index out of the main
docs page.
We want to autodoc the modules so we can view the actual module index in
the tox -d docs build results, which also tells us if we have correct
ReST format in doc strings.
Notes
-----
1. Several doc string blocks have to be fixed as part of this to get
the docs tox job to pass.
2. A docstring in vhdutilsv2 is updated to remove the math directive
since that requires the sphinx.ext.pngmath extension which requires
latex and dvipng packages from the distro - which is overkill for
what the docstring was actually doing with the math directive.
3. We exclude autodoc for tests since we don't really care about
docstrings on unit tests.
4. We exclude the nova.wsgi.nova-* modules since those won't build with
autodoc since they can't be imported (there is no
nova/wsgi/__init__.py module). We could arguably add the __init__.py
but it's not really necessary for what those scripts are used for.
5. The sphinx.ext.ifconfig extension is removed since there are no docs
that use the ifconfig directive.
6. Update the developer docs to explicitly point out that graphviz must
be installed prior to running tox -e docs.
7. Hide doc/source/api/autoindex.rst from the toctree so that we don't
regress the point of commit bd7e62f796.
8. unused_docs and exclude_trees options are removed from conf.py since
they are deprecated in Sphinx 1.2.3:
https://github.com/sphinx-doc/sphinx/blob/1.2.3/sphinx/config.py#L54
9. Fix imports for moved libvirt volume options.
Closes-Bug: #1471934
Change-Id: I946e2f89f2c9fc70e870faaf84e4a8b0fc703344
This commit adds some (long overdue) documentation around block device
mapping and how it's used in Nova.
blueprint devref-refresh-liberty
Change-Id: Idca142f3b34ad896ab99f02a3f9eb72a6a3b4778
Adding docs to make it clear how to get more involved.
As a first step, lets link to the docs we are working on in the wiki.
At a later date we can graduate the wiki docs into here.
blueprint devref-refresh-liberty
Change-Id: If6c24bc4522eab72354c1602ceaa07352104a34d
Reorganized the developer docs so its clear between whats are future
plans and what things are documenting the current behavior.
Given a lot of the API docs are currently in flux, I have classed those
as future plans.
blueprint devref-refresh-liberty
Co-Authored-By: Michael Still <mikal@stillhq.com>
Change-Id: Ie79fcef909487ee1797274f0ca23854b2fb49d32
- Changes api to API to force build of all source files.
- Ensures tracking is consistent across all openstack.org web properties.
- Tracks only docs.openstack.org/developer/{{ project }} where
project name is taken from conf.py.
- Removes ability to build local without GA. If you have ideas
for how to build local without GA, please patch.
Change-Id: Ibb61e5c1668e6a0782daf91d4faf0950c5bf77d7
Partial-bug: 1441315
This document describes the expect of Nova REST API from Nova team. Also can
resolve some confuse what you see in the current Nova code. The Nova team will
try to reach the final goal of this document described.
Co-Authored-By: Jay Pipes <jaypipes@gmail.com>
Change-Id: Ia837bca561fa8a7c48eadfcd9bd791dc8c8d29ac
Make the API microversion history more accessible by adding it to nova's
doc landing page.
Making sure it is easy to discover what the difference between each
microversion is fundamental piece of the microversion puzzle, so lets
not require end users to have to look through git.
rename api_microversions.rst to api_microversion_dev.rst to clarify that
it is about development and versus history.
Change-Id: I270944bf9739b113a43b932948fdbf83e449603b
Previously kilo.blueprints was a document to propose a change to the
blueprints process. Turn the document into a reference for blueprints,
specs and priorities in nova.
* Just state current policy instead of references to how it was
before. This information will still be around in the git history if we
never need to look it up.
* Now that we have been doing this for a cycle we don't need hypothetical
examples anymore.
* Make this reflect the fact that we just use an etherpad to track
* priority reviews.
Change-Id: I0d6e568fe1a8ef40de1d7f7d7e45260b1400e407
All of that information can be found at
http://docs.openstack.org/infra/manual/developers.html, so just make the
link to developers.html more prominent in development.environment
* Rename development.environment to a shorter title, Developer quickstart.
Change-Id: I1460e6c86a7e0a1efb4a81c6c5cb594476171214
* Explain these docs are for trunk (copied from ironic)
* All the docs in this repo are meant to be developer docs, so having a
devref inside of the docs is redundant and just makes the docs more
complicated to navigate. Move everything out of the devref folder and
link to everything from main index.
* Move man pages into separate section. The man pages are pretty sparse
* right now, we should either make them useful or just delete them
* Remove dead docs from unused_docs list in doc/source/conf.py
* Shuffle docs landing page, move common referees to the top (API,
hypervisor support matrix), Add a introduction section and more. The
hope is the updated layout makes this document easier to navigate.
* Use maxdepth of 1
* Rename a few sections with what are hopefully better names
The next step is to prune out outdated documents and further cleanup
this page.
Change-Id: Iff453e47ccc902a0e72b1a5f6ce1ee939ff3a1a0
Stephen Finucane