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
This is developer oriented documentation, make sure that is clear and
point to docs.openstack.org for more docs.
Change-Id: I0680e331b0fcf57dddb157c99e59d690fea349cb
This adds a document that helps clarify the scope of the Nova mission
statement.
We need to keep the Nova project a manageable size. Agreeing on what
Nova should focus on is a great way to make sure we grow Nova in a
consistent way, leaving open opportunities for other projects to do a
better job of things Nova doesn't see as part of its core mission.
Part of blueprint devref-refresh-liberty
Change-Id: I4e46ee252e6b29b063bcc8204d60d670eb79daef
Our docs our wildly out of date and pretty bad, this is a first step at
beginning to clean them up and make them more useful.
* remove the guidelines section. 2 of them are explicitly wrong (API
Compatibility and Open Standards), and no one actually uses these
guidelines during development. Yes we want high availability and fault
tolerance, but listing these design guidelines here is misleading at
best.
* Don't explain how this document is built, don't need to explain that
so prominently
* Update the intro based on Nova's mission statement
Change-Id: Ia564a7cacdac0ddab913464ca1c7f9fefb0ee0b5
The toctree was globbing a nonexistent directory, and not producing
useful output. This patch lists the contents correctly.
Change-Id: I414120d948bd3eeeec84ac279bab11c276ef5eee
Per email discussion[1], v2.1 API is our CURRENT when we get to kilo and
v2 is SUPPORTED. Added links to the v2.1 API, v2 API and v2 extensions
API in our documentation
[1] http://markmail.org/message/p32p5jbvvjedg657
Depends-On: Ibe990ec93d8f9d18ef21c28979e180472df6a33d
Closes-Bug: #1435507
Change-Id: Iaa62be9612dd039f7669ff2b5587c922aba54093
Add document to replace / obsolete the giant table on
https://wiki.openstack.org/wiki/HypervisorSupportMatrix
This initial draft is a fairly straightforward conversion of
that table. Over time, it needs much work to improve the coverage
of API operations and and coverage of important configuration
information that users will care about.
It is using the .ini file syntax in order to record the data in
an easily machine parsable format, while remaining human friendly
by avoiding the syntax heavy approach of XML / JSON / YAML
An extension is registered with sphinx that can convert the
.ini file content into docutils content that then gets rendered
into the developer docs, linked from the index page
Change-Id: I4d3db4bce5737dba30a026a11083a9ea64459cd4
Don't list entire api/autoindex under Developer Docs, we already have a
model index link at the bottom of the page, showing the entire
autoindex on the home page is makes the page overwhelming.
Change-Id: I25c5b50412881b55aa745ce3da2c22466e879fcf
By setting this pbr option in setup.cfg, the doc build will fail in case
of any warnings or errors occur during the build process.
Closes-Bug: #1351350
Change-Id: Id4858062d2aaa4c2fe5b597e40e4e8947f544a4d
The doc todo list didn't actually work, so remove it. Also, the
documentation is not written by Anso Labs quite so much anymore.
Change-Id: I746a26505d331ab55565e952a1a46425458b1412
blueprint sphinx-doc-cleanup
bug 944385
- Fix formatting and markup issues that produce error messages
- Update TOC lists for missing/new files
- Fix a few links
- Update instructions with dependencies for building the documentation
- Updated base on review comments from oubiwann to fix trailing whitespace in modified files
Change-Id: I589152bfab9c543d2b11fa8bed2344259aa90675
This patch fixes the docs so that the API extensions documentation gets
included. In passing, also update the API extensions index to include
an extension that was not listed.
Change-Id: Ia16cab2b29bbc121d940dc4ed9f033340935cde8
Michael Still