openstack/nova
Code Issues Proposed changes
53f752a669
nova/doc/source/index.rst

257 lines
7.4 KiB
ReStructuredText
Raw Normal View History

initial commit
2010-05-27 23:05:26 -07:00
..
Removes RST documentation and moves it to openstack-manuals Avoiding redundant information and confusion. Change-Id: Iab1913ff359699db977b74554bad6088fab6ab2f
2012-04-30 12:45:10 -05:00
Copyright 2010-2012 United States Government as represented by the
Remove trailing whitespaces in regular file Fixes bug #945346 Change-Id: I07a303c2e503e50d7138585c683e0d1310339276
2012-03-07 13:43:37 +08:00
Administrator of the National Aeronautics and Space Administration.
Updated licenses
2010-06-23 22:04:16 -07:00
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
initial commit
2010-05-27 23:05:26 -07:00
http://www.apache.org/licenses/LICENSE-2.0
Updated licenses
2010-06-23 22:04:16 -07:00
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
initial commit
2010-05-27 23:05:26 -07:00
Update docs layout * 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
2015-05-14 14:18:53 -07:00
==========================================
Removes RST documentation and moves it to openstack-manuals Avoiding redundant information and confusion. Change-Id: Iab1913ff359699db977b74554bad6088fab6ab2f
2012-04-30 12:45:10 -05:00
Welcome to Nova's developer documentation!
==========================================
initial commit
2010-05-27 23:05:26 -07:00
Cleanup docs landing page 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
2015-05-01 19:21:58 -07:00
Nova is an OpenStack project designed to provide power massively scalable, on
demand, self service access to compute resources.
New structure for documentation.
2010-10-27 00:05:42 -04:00
Update docs layout * 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
2015-05-14 14:18:53 -07:00
The developer documentation provided here is continually kept up-to-date
based on the latest code, and may not represent the state of the project at
any specific prior release.
Add note to doc explaining scope This is developer oriented documentation, make sure that is clear and point to docs.openstack.org for more docs. Change-Id: I0680e331b0fcf57dddb157c99e59d690fea349cb
2015-05-13 12:34:40 -07:00
.. note:: This is documentation for developers, if you are looking for more
general documentation including API, install, operator and user
guides see `docs.openstack.org`_
Fix a couple dead links in docs 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
2015-08-04 22:03:51 -07:00
.. _`docs.openstack.org`: http://docs.openstack.org
Add note to doc explaining scope This is developer oriented documentation, make sure that is clear and point to docs.openstack.org for more docs. Change-Id: I0680e331b0fcf57dddb157c99e59d690fea349cb
2015-05-13 12:34:40 -07:00
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
This documentation is intended to help explain what the Nova developers think
is the current scope of the Nova project, as well as the architectural
decisions we have made in order to support that scope. We also document our
plans for evolving our architecture over time. Finally, we documented our
current development process and policies.
Create For End Users index section 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
2017-08-08 08:38:23 -04:00
For End Users
=============
As an end user of nova, you'll use nova to create and manage servers with
either tools or the API directly.
Tools for using Nova
--------------------
* `Horizon
<https://docs.openstack.org/horizon/latest/user/launch-instances.html>`_: The
official web ui for the OpenStack Project.
* `OpenStack Client
<https://docs.openstack.org/python-openstackclient/latest/>`_: The official
CLI for OpenStack Projects. You should use this as your CLI for most things,
it includes not just nova commands but also commands for most of the projects
in OpenStack.
* `Nova Client
<https://docs.openstack.org/python-novaclient/latest/user/shell.html>`_: For
some very advanced features (or administrative commands) of nova you may need
to use nova client. It is still supported, but the ``openstack`` cli is
recommended.
Writing to the API
------------------
All end user (and some administrative) features of nova are exposed via a REST
API, which can be used to build more complicated logic or automation with
nova. This can be consumed directly, or via various SDKs. The following
resources will help you get started with consuming the API directly.
* `Compute API Guide: <https://developer.openstack.org/api-guide/compute/>`_: The
concept guide for the API. This helps lay out the concepts behind the API to
make consuming the API reference easier.
* `Compute API Reference <http://developer.openstack.org/api-ref/compute/>`_:
The complete reference for the API, including all methods and request /
response parameters and their meaning.
* `API Microversion History <reference/api-microversion-history>`_: The
compute API evolves over time through `Microversions
<https://developer.openstack.org/api-guide/compute/microversions.html>`_. This
provides the history of all those changes. Consider it a "what's new" in the
compute API.
docs: add link to liberty summit session on v2.1 API 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
2015-08-07 12:07:24 -07:00
Update docs layout * 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
2015-05-14 14:18:53 -07:00
docs: add test strategy and feature classification 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
2015-08-21 15:28:22 +01:00
Feature Status
==============
initial commit
2010-05-27 23:05:26 -07:00
docs: add test strategy and feature classification 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
2015-08-21 15:28:22 +01:00
Nova aims to have a single compute API that works the same across
all deployments of Nova.
While many features are well-tested, well-documented, support live upgrade,
and are ready for production, some are not. Also the choice of underlying
technology affects the list of features that are ready for production.
Our first attempt to communicate this is the feature support matrix
(previously called the hypervisor support matrix).
Over time we hope to evolve that to include a classification of each feature's
maturity and exactly what technology combinations are covered by current
integration testing efforts.
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
initial commit
2010-05-27 23:05:26 -07:00
.. toctree::
New structure for documentation.
2010-10-27 00:05:42 -04:00
:maxdepth: 1
doc: Populate the 'user' section 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
2017-06-29 09:48:01 +01:00
user/feature-classification
user/support-matrix
additions to home page
2010-11-05 11:56:12 -07:00
Create reference subpage 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
2017-08-04 13:18:41 -04:00
For Contributors
================
Update docs layout * 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
2015-05-14 14:18:53 -07:00
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
If you are new to Nova, this should help you start to understand what Nova
actually does, and why.
Adds Compute API v2 docs Imported from public API docs plus fixes to make them more accurate. Change-Id: I6d5ba6b96772e0f17fc7484312222110ec103bbf
2014-12-17 10:14:37 -06:00
.. toctree::
:maxdepth: 1
Add Contributor Guide section page 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
2017-08-03 16:36:10 -04:00
contributor/index
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
Create reference subpage 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
2017-08-04 13:18:41 -04:00
There are also a number of technical references on both current and future
looking parts of our architecture. These are collected below.
.. toctree::
:maxdepth: 1
reference/index
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
Architecture Concepts
----------------------
This follows on for the discussion in the introduction, and digs into
details on specific parts of the Nova architecture.
We find it important to document the reasons behind our architectural
decisions, so its easier for people to engage in the debates about
the future of Nova's architecture. This is all part of Open Design and
Open Development.
Update docs layout * 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
2015-05-14 14:18:53 -07:00
doc: Don't put comments inside toctree 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
2017-02-23 16:09:39 -05:00
.. NOTE: keep this list sorted by title
Update docs layout * 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
2015-05-14 14:18:53 -07:00
.. toctree::
:maxdepth: 1
Add Contributor Guide section page 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
2017-08-03 16:36:10 -04:00
user/architecture
doc: Populate the 'user' section 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
2017-06-29 09:48:01 +01:00
user/block-device-mapping
user/conductor
user/filter-scheduler
user/aggregates
user/placement
user/quotas
user/wsgi
docs: clear between current vs future plans 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
2015-06-16 14:37:16 +01:00
Architecture Evolution Plans
-----------------------------
The following section includes documents that describe the overall plan behind
groups of nova-specs. Most of these cover items relating to the evolution of
various parts of Nova's architecture. Once the work is complete,
these documents will move into the "Concepts" section.
If you want to get involved in shaping the future of Nova's architecture,
these are a great place to start reading up on the current plans.
Update docs layout * 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
2015-05-14 14:18:53 -07:00
.. toctree::
:maxdepth: 1
Add some more cellsv2 doc goodness 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
2017-07-25 12:13:42 -07:00
user/cellsv2_layout
doc: Populate the 'user' section 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
2017-06-29 09:48:01 +01:00
user/upgrade
Update docs layout * 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
2015-05-14 14:18:53 -07:00
doc: Start using oslo_config.sphinxext 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
2017-08-03 16:24:53 +01:00
Configuration
-------------
Add sample config file to nova docs 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
2015-08-13 16:18:46 -04:00
.. toctree::
:maxdepth: 1
doc: Start using oslo_config.sphinxext 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
2017-08-03 16:24:53 +01:00
configuration/config
doc: Populate the 'configuration' section 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
2017-06-27 11:07:24 +01:00
configuration/sample-config
Add sample config file to nova docs 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
2015-08-13 16:18:46 -04:00
doc: Start using oslo_policy.sphinxext 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
2017-08-03 16:34:25 +01:00
Policy
------
doc: Integrate oslo_policy.sphinxpolicygen Change-Id: I80e75b8a592e1125e02ca6177661177a7c17c927
2016-09-26 14:53:18 +01:00
.. toctree::
:maxdepth: 1
doc: Start using oslo_policy.sphinxext 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
2017-08-03 16:34:25 +01:00
configuration/policy
doc: Populate the 'configuration' section 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
2017-06-27 11:07:24 +01:00
configuration/sample-policy
Add sample config file to nova docs 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
2015-08-13 16:18:46 -04:00
Update docs layout * 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
2015-05-14 14:18:53 -07:00
Man Pages
----------
.. toctree::
:maxdepth: 1
doc: Populate the 'cli' section 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
2017-06-27 11:01:38 +01:00
cli/index
Update docs layout * 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
2015-05-14 14:18:53 -07:00
Set autodoc_index_modules=True so tox -e docs builds module docs again Commit bd7e62f796fe951fd42c2edad56e252a0b7393c8 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 bd7e62f796fe951fd42c2edad56e252a0b7393c8. 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
2015-07-06 15:18:59 -07:00
.. # NOTE(mriedem): This is the section where we hide things that we don't
# actually want in the table of contents but sphinx build would fail if
# they aren't in the toctree somewhere. For example, we hide api/autoindex
# since that's already covered with modindex below.
.. toctree::
:hidden:
Add Contributor Guide section page 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
2017-08-03 16:36:10 -04:00
contributor/development-environment
contributor/api
contributor/api-2
contributor/blueprints
contributor/code-review
contributor/microversions
contributor/placement.rst
contributor/policies.rst
contributor/releasenotes
contributor/testing
contributor/testing/libvirt-numa
contributor/testing/serial-console
contributor/testing/zero-downtime-upgrade
contributor/how-to-get-involved
contributor/process
contributor/project-scope
Create reference subpage 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
2017-08-04 13:18:41 -04:00
user/cells
Create For End Users index section 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
2017-08-08 08:38:23 -04:00
reference/api-microversion-history.rst
Create reference subpage 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
2017-08-04 13:18:41 -04:00
reference/gmr
reference/i18n
reference/notifications
reference/policy-enforcement
reference/rpc
reference/scheduler-evolution
reference/services
reference/stable-api
reference/threading
reference/vm-states
Add Contributor Guide section page 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
2017-08-03 16:36:10 -04:00
doc: Import installation guide Import all docs from openstack-manuals. Part of bp: doc-migration Change-Id: If1fa15f5495a8a207042e7a43d34d32671c59ee1 Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
2017-06-26 10:56:29 +00:00
Installation Guide
==================
.. toctree::
:maxdepth: 2
install/index
Documentation for the vendordata reboot. Change-Id: I893bc574ba049250f1d06adc2b7f85eac21da1cf Blueprint: vendordata-reboot
2016-08-11 10:31:28 +10:00
Metadata
========
.. toctree::
:maxdepth: 1
doc: Populate the 'user' section 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
2017-06-29 09:48:01 +01:00
user/vendordata
Documentation for the vendordata reboot. Change-Id: I893bc574ba049250f1d06adc2b7f85eac21da1cf Blueprint: vendordata-reboot
2016-08-11 10:31:28 +10:00
Create reference subpage 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
2017-08-04 13:18:41 -04:00
Administration Guide
doc: Import administration guide Import all docs from openstack-manuals. Part of bp: doc-migration Change-Id: I28bb8ce1f4a8653f176a554d2e95b4423c437972 Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>
2017-06-26 11:27:52 +00:00
====================
.. toctree::
:maxdepth: 2
admin/index
initial commit
2010-05-27 23:05:26 -07:00
Indices and tables
==================
* :ref:`search`
Copy Permalink