openstack/nova
Code Issues Proposed changes
3f12c8badd
nova/doc/source/index.rst

242 lines
6.7 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.
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
Compute API References
Changes conf.py for Sphinx build because oslosphinx now contains GA - 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
2015-04-09 12:40:04 -05:00
======================
fix developer docs on API 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
2016-06-22 15:06:12 -04:00
The Nova compute API is quite large, we provide a concept guide which
gives some of the high level details, as well as a more detailed API
reference.
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
fix developer docs on API 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
2016-06-22 15:06:12 -04:00
The API reference covers all versions of the API. Version 2.0 and
Version 2.1 are actually the same API, and Version 2.1 evolves forward
with microversions. The API ref starts with the base API version, and
specifies all changes that exist to it as microversions roll
forward. You can also see a history of our microversions here:
Link to microversion history in docs 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
2015-06-10 18:31:58 +03:00
.. toctree::
:maxdepth: 1
doc: Populate the 'reference' section 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
2017-06-28 12:23:19 +01:00
reference/api-microversion-history
Link to microversion history in docs 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
2015-06-10 18:31:58 +03:00
Mention API V2 should no longer be used 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
2016-10-17 22:32:09 -05:00
.. note::
Only Version 2.1 APIs should be used from this point forward, Version 2.0
APIs are only provided for backward compatibility purposes.
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
Rearranges to create new Compute API Guide 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
2015-10-01 17:27:50 -05:00
.. _`Compute API Guide`: http://developer.openstack.org/api-guide/compute/
fix developer docs on API 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
2016-06-22 15:06:12 -04:00
.. _`Compute API Reference`: http://developer.openstack.org/api-ref/compute/
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 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
There was a session on the v2.1 API at the Liberty summit which you can watch
`here <https://www.openstack.org/summit/vancouver-2015/summit-videos/presentation/introduction-of-a-new-nova-rest-api-why-we-need-to-use-nova-v2-1-api>`_.
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
reference/gmr
reference/i18n
reference/notifications
reference/policy-enforcement
reference/rpc
reference/scheduler-evolution
reference/services
reference/stable-api
reference/threading
reference/vm-states
reference/i18n
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