Missing from our contributor guides is documentation guidelines,
starting a page there for now especially as there are a couple of
things that emerged in the great pike import that would be good to
write down.
Part of bp: doc-migration
Change-Id: Ib2b49f70c55311195535a5ef250ff555e227fa0a
Import the following files from the former config-reference [1]:
api.rst
cells.rst
fibre-channel.rst
hypervisor-basics.rst
hypervisor-hyper-v.rst
hypervisor-kvm.rst
hypervisor-lxc.rst
hypervisor-qemu.rst
hypervisor-virtuozzo.rst
hypervisor-vmware.rst
hypervisor-xen-api.rst
hypervisor-xen-libvirt.rst
hypervisors.rst
index.rst
iscsi-offload.rst
logs.rst
resize.rst
samples/api-paste.ini.rst
samples/index.rst
samples/policy.yaml.rst
samples/rootwrap.conf.rst
schedulers.rst
The below files are skipped as they're already included, in slightly
different forms, in the nova documentation.
config-options.rst
nova-conf-samples.rst
nova-conf.rst
nova.conf
Part of bp: doc-migration
Change-Id: I145e38149bf20a5e068f8cfe913f90c7ebeaad36
The index previously was written for the developer docs, but this is
more than developer docs now. That also means this is the general
google landing page for people, so a basic "what is nova" is
appropriate.
Part of bp: doc-migration
Change-Id: I5fdafd9f6cf07a19bf86a6343663dad410887dcb
This attempts to reorganize the front page content relevant to
operators into digestable chunks, including some summaries of links to
explain to people why they might want to follow those links to learn
more.
Part of bp: doc-migration
Change-Id: I6815958b2533d462a2e5d27e7be57440d9f4f40a
This reorganizes the pieces that are for end users into a convenient
chunk up front in the main index page.
Part of bp: doc-migration
Change-Id: Ic2fcabbf3faa531fccb19cffa2564f005142e463
In an attempt to make the main navigation sidebar not be visual mud
(and really confusing) create a reference sub page that explains all
the references.
Part of bp: doc-migration
Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
In order to wrangle together a top level TOC that makes sense, stop
including everything in the TOC (ideally we could convince sphinx to
not warn on that).
This creates a Contributor Documentation landing page with deep links
to all the relevant documents. It removes all those links from the
front page, and the TOC. They can be found by deep links or search,
and it is a less confusing initial experience for folks.
Part of bp: doc-migration
Change-Id: If5e7940ddd0ae3316f7475742c02abfe3df28ac4
Import all docs from openstack-manuals.
Part of bp: doc-migration
Change-Id: I28bb8ce1f4a8653f176a554d2e95b4423c437972
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
Import all docs from openstack-manuals.
Part of bp: doc-migration
Change-Id: If1fa15f5495a8a207042e7a43d34d32671c59ee1
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
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
Sean Dague