From a1e8fc6dd98bc10fed3220764ce9dffc70c930c8 Mon Sep 17 00:00:00 2001 From: Joe Gordon Date: Thu, 14 May 2015 14:18:53 -0700 Subject: [PATCH] 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 --- .../{devref => }/addmethod.openstackapi.rst | 0 doc/source/{devref => }/aggregates.rst | 0 doc/source/{devref => }/api_microversions.rst | 0 doc/source/{devref => }/api_plugins.rst | 0 doc/source/{devref => }/architecture.rst | 0 doc/source/{devref => }/cells.rst | 0 doc/source/conf.py | 3 - .../{devref => }/development.environment.rst | 0 doc/source/devref/index.rst | 94 ------------- doc/source/{devref => }/filter_scheduler.rst | 4 +- doc/source/{devref => }/gerrit.rst | 0 doc/source/{devref => }/gmr.rst | 0 doc/source/{devref => }/hooks.rst | 0 doc/source/{devref => }/i18n.rst | 0 doc/source/index.rst | 123 +++++++++++++++--- doc/source/{devref => }/jenkins.rst | 0 doc/source/{devref => }/kilo.blueprints.rst | 0 doc/source/{devref => }/launchpad.rst | 0 doc/source/man/index.rst | 2 +- doc/source/{devref => }/policies.rst | 0 .../{devref => }/policy_enforcement.rst | 0 doc/source/{devref => }/project_scope.rst | 0 doc/source/{devref => }/rpc.rst | 12 +- doc/source/{devref => }/services.rst | 0 .../{devref => }/testing/libvirt-numa.rst | 0 .../{devref => }/testing/serial-console.rst | 0 doc/source/{devref => }/threading.rst | 0 doc/source/{devref => }/unit_tests.rst | 0 doc/source/{devref => }/upgrade.rst | 0 doc/source/{devref => }/vmstates.rst | 6 +- 30 files changed, 114 insertions(+), 130 deletions(-) rename doc/source/{devref => }/addmethod.openstackapi.rst (100%) rename doc/source/{devref => }/aggregates.rst (100%) rename doc/source/{devref => }/api_microversions.rst (100%) rename doc/source/{devref => }/api_plugins.rst (100%) rename doc/source/{devref => }/architecture.rst (100%) rename doc/source/{devref => }/cells.rst (100%) rename doc/source/{devref => }/development.environment.rst (100%) delete mode 100644 doc/source/devref/index.rst rename doc/source/{devref => }/filter_scheduler.rst (99%) rename doc/source/{devref => }/gerrit.rst (100%) rename doc/source/{devref => }/gmr.rst (100%) rename doc/source/{devref => }/hooks.rst (100%) rename doc/source/{devref => }/i18n.rst (100%) rename doc/source/{devref => }/jenkins.rst (100%) rename doc/source/{devref => }/kilo.blueprints.rst (100%) rename doc/source/{devref => }/launchpad.rst (100%) rename doc/source/{devref => }/policies.rst (100%) rename doc/source/{devref => }/policy_enforcement.rst (100%) rename doc/source/{devref => }/project_scope.rst (100%) rename doc/source/{devref => }/rpc.rst (98%) rename doc/source/{devref => }/services.rst (100%) rename doc/source/{devref => }/testing/libvirt-numa.rst (100%) rename doc/source/{devref => }/testing/serial-console.rst (100%) rename doc/source/{devref => }/threading.rst (100%) rename doc/source/{devref => }/unit_tests.rst (100%) rename doc/source/{devref => }/upgrade.rst (100%) rename doc/source/{devref => }/vmstates.rst (96%) diff --git a/doc/source/devref/addmethod.openstackapi.rst b/doc/source/addmethod.openstackapi.rst similarity index 100% rename from doc/source/devref/addmethod.openstackapi.rst rename to doc/source/addmethod.openstackapi.rst diff --git a/doc/source/devref/aggregates.rst b/doc/source/aggregates.rst similarity index 100% rename from doc/source/devref/aggregates.rst rename to doc/source/aggregates.rst diff --git a/doc/source/devref/api_microversions.rst b/doc/source/api_microversions.rst similarity index 100% rename from doc/source/devref/api_microversions.rst rename to doc/source/api_microversions.rst diff --git a/doc/source/devref/api_plugins.rst b/doc/source/api_plugins.rst similarity index 100% rename from doc/source/devref/api_plugins.rst rename to doc/source/api_plugins.rst diff --git a/doc/source/devref/architecture.rst b/doc/source/architecture.rst similarity index 100% rename from doc/source/devref/architecture.rst rename to doc/source/architecture.rst diff --git a/doc/source/devref/cells.rst b/doc/source/cells.rst similarity index 100% rename from doc/source/devref/cells.rst rename to doc/source/cells.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 257db7492989..14612595c313 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -84,9 +84,6 @@ version = version_info.version_string() # List of documents that shouldn't be included in the build. unused_docs = [ - 'api_ext/rst_extension_template', - 'vmwareapi_readme', - 'installer', ] # List of directories, relative to source directory, that shouldn't be searched diff --git a/doc/source/devref/development.environment.rst b/doc/source/development.environment.rst similarity index 100% rename from doc/source/devref/development.environment.rst rename to doc/source/development.environment.rst diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst deleted file mode 100644 index a21ec0f4d9ad..000000000000 --- a/doc/source/devref/index.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - 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 - - http://www.apache.org/licenses/LICENSE-2.0 - - 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. - -Developer Guide -=============== - -In this section you will find information on Nova's lower level programming APIs. - - -Programming HowTos and Tutorials --------------------------------- -.. toctree:: - :maxdepth: 3 - - development.environment - unit_tests - addmethod.openstackapi - gmr - api_plugins - api_microversions - -Background Concepts for Nova ----------------------------- -.. toctree:: - :maxdepth: 3 - - architecture - aggregates - cells - threading - vmstates - i18n - filter_scheduler - rpc - hooks - upgrade - policy_enforcement - -Development policies --------------------- -.. toctree:: - :maxdepth: 3 - - kilo.blueprints - policies - project_scope - -Testing guides --------------- - -.. toctree:: - :maxdepth: 3 - - testing/libvirt-numa - testing/serial-console - -Other Resources ---------------- -.. toctree:: - :maxdepth: 3 - - launchpad - gerrit - jenkins - -Module Reference ----------------- -.. toctree:: - :maxdepth: 3 - - services - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/devref/filter_scheduler.rst b/doc/source/filter_scheduler.rst similarity index 99% rename from doc/source/devref/filter_scheduler.rst rename to doc/source/filter_scheduler.rst index 834543c1b277..a7ea5e2b71f2 100644 --- a/doc/source/devref/filter_scheduler.rst +++ b/doc/source/filter_scheduler.rst @@ -8,7 +8,7 @@ only working with Compute Nodes. Filtering --------- -.. image:: ../images/filteringWorkflow1.png +.. image:: ./images/filteringWorkflow1.png During its work Filter Scheduler firstly makes dictionary of unfiltered hosts, then filters them using filter properties and finally chooses hosts for the @@ -370,7 +370,7 @@ so subsequent selections can adjust accordingly. It is useful if the customer asks for the some large amount of instances, because weight is computed for each instance requested. -.. image:: ../images/filteringWorkflow2.png +.. image:: ./images/filteringWorkflow2.png In the end Filter Scheduler sorts selected hosts by their weight and provisions instances on them. diff --git a/doc/source/devref/gerrit.rst b/doc/source/gerrit.rst similarity index 100% rename from doc/source/devref/gerrit.rst rename to doc/source/gerrit.rst diff --git a/doc/source/devref/gmr.rst b/doc/source/gmr.rst similarity index 100% rename from doc/source/devref/gmr.rst rename to doc/source/gmr.rst diff --git a/doc/source/devref/hooks.rst b/doc/source/hooks.rst similarity index 100% rename from doc/source/devref/hooks.rst rename to doc/source/hooks.rst diff --git a/doc/source/devref/i18n.rst b/doc/source/i18n.rst similarity index 100% rename from doc/source/devref/i18n.rst rename to doc/source/i18n.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ee618dc4bf06..09e3f17bb6cc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,49 +15,130 @@ License for the specific language governing permissions and limitations under the License. +========================================== Welcome to Nova's developer documentation! ========================================== Nova is an OpenStack project designed to provide power massively scalable, on demand, self service access to compute resources. +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. + .. 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`_ .. _`docs.openstack.org`: https://docs.openstack.org +Compute API References +======================= +* `v2.1 (CURRENT)`_ +* `v2 (SUPPORTED)`_ and `v2 extensions (SUPPORTED)`_ (Will be deprecated in + the near future.) -Developer Docs -============== - -.. toctree:: - :maxdepth: 1 - - devref/index - man/index - support-matrix - devref/project_scope - -Compute API v2 -============== +Local copy of v2 docs: .. toctree:: :maxdepth: 1 v2/index -API Extensions -============== -Go to the `API Complete Reference v2.1 (CURRENT)`_ for information about the Compute API. -We still support the older `API Complete Reference v2 (SUPPORTED)`_ and its extensions -`API Complete Reference v2 extensions (SUPPORTED)`_ +.. _`v2.1 (CURRENT)`: http://developer.openstack.org/api-ref-compute-v2.1.html +.. _`v2 (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2.html +.. _`v2 extensions (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2-ext.html -.. _`API Complete Reference v2.1 (CURRENT)`: http://developer.openstack.org/api-ref-compute-v2.1.html -.. _`API Complete Reference v2 (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2.html -.. _`API Complete Reference v2 extensions (SUPPORTED)`: http://developer.openstack.org/api-ref-compute-v2-ext.html + + +Hypervisor Support Matrix +========================= + +.. toctree:: + :maxdepth: 1 + + support-matrix + +Developer Guide +=============== + +Introduction +------------- + +.. toctree:: + :maxdepth: 1 + + architecture + project_scope + +.. toctree:: + :maxdepth: 1 + + development.environment + unit_tests + launchpad + gerrit + jenkins + +APIs Development +---------------- +.. toctree:: + :maxdepth: 1 + + addmethod.openstackapi + api_plugins + api_microversions + policy_enforcement + +Concepts +--------- +.. toctree:: + :maxdepth: 1 + + aggregates + cells + threading + vmstates + i18n + filter_scheduler + rpc + hooks + upgrade + +Development policies +-------------------- +.. toctree:: + :maxdepth: 1 + + kilo.blueprints + policies + +Advanced testing and guides +---------------------------- + +.. toctree:: + :maxdepth: 1 + + gmr + testing/libvirt-numa + testing/serial-console + +Man Pages +---------- + +.. toctree:: + :maxdepth: 1 + + man/index + +Module Reference +---------------- +.. toctree:: + :maxdepth: 1 + + services Indices and tables ================== diff --git a/doc/source/devref/jenkins.rst b/doc/source/jenkins.rst similarity index 100% rename from doc/source/devref/jenkins.rst rename to doc/source/jenkins.rst diff --git a/doc/source/devref/kilo.blueprints.rst b/doc/source/kilo.blueprints.rst similarity index 100% rename from doc/source/devref/kilo.blueprints.rst rename to doc/source/kilo.blueprints.rst diff --git a/doc/source/devref/launchpad.rst b/doc/source/launchpad.rst similarity index 100% rename from doc/source/devref/launchpad.rst rename to doc/source/launchpad.rst diff --git a/doc/source/man/index.rst b/doc/source/man/index.rst index 46f5c17ff03f..83b9879aa18f 100644 --- a/doc/source/man/index.rst +++ b/doc/source/man/index.rst @@ -23,7 +23,7 @@ In this section you will find information on Nova's command line utilities. Reference --------- .. toctree:: - :maxdepth: 3 + :maxdepth: 1 nova-all nova-api-ec2 diff --git a/doc/source/devref/policies.rst b/doc/source/policies.rst similarity index 100% rename from doc/source/devref/policies.rst rename to doc/source/policies.rst diff --git a/doc/source/devref/policy_enforcement.rst b/doc/source/policy_enforcement.rst similarity index 100% rename from doc/source/devref/policy_enforcement.rst rename to doc/source/policy_enforcement.rst diff --git a/doc/source/devref/project_scope.rst b/doc/source/project_scope.rst similarity index 100% rename from doc/source/devref/project_scope.rst rename to doc/source/project_scope.rst diff --git a/doc/source/devref/rpc.rst b/doc/source/rpc.rst similarity index 98% rename from doc/source/devref/rpc.rst rename to doc/source/rpc.rst index 3c04982dd14c..94eadb21e299 100644 --- a/doc/source/devref/rpc.rst +++ b/doc/source/rpc.rst @@ -1,4 +1,4 @@ -.. +. Copyright (c) 2010 Citrix Systems, Inc. All Rights Reserved. @@ -25,7 +25,7 @@ AMQP is the messaging technology chosen by the OpenStack cloud. The AMQP broker Nova uses direct, fanout, and topic-based exchanges. The architecture looks like the one depicted in the figure below: -.. image:: ../images/rpc/arch.png +.. image:: ./images/rpc/arch.png :width: 60% .. @@ -47,7 +47,7 @@ Figure 2 shows the following internal elements: * Direct Exchange: this is a routing table that is created during rpc.call operations; there are many instances of this kind of exchange throughout the life-cycle of a message broker node, one for each rpc.call invoked. * Queue Element: A Queue is a message bucket. Messages are kept in the queue until a Consumer (either Topic or Direct Consumer) connects to the queue and fetch it. Queues can be shared or can be exclusive. Queues whose routing key is 'topic' are shared amongst Workers of the same personality. -.. image:: ../images/rpc/rabt.png +.. image:: ./images/rpc/rabt.png :width: 60% .. @@ -62,7 +62,7 @@ The diagram below shows the message flow during an rpc.call operation: 3. once the task is completed, a Direct Publisher is allocated to send the response message to the queuing system. 4. once the message is dispatched by the exchange, it is fetched by the Direct Consumer dictated by the routing key (such as 'msg_id') and passed to the Invoker. -.. image:: ../images/rpc/flow1.png +.. image:: ./images/rpc/flow1.png :width: 60% .. @@ -75,7 +75,7 @@ The diagram below shows the message flow during an rpc.cast operation: 1. A Topic Publisher is instantiated to send the message request to the queuing system. 2. Once the message is dispatched by the exchange, it is fetched by the Topic Consumer dictated by the routing key (such as 'topic') and passed to the Worker in charge of the task. -.. image:: ../images/rpc/flow2.png +.. image:: ./images/rpc/flow2.png :width: 60% .. @@ -100,7 +100,7 @@ The figure below shows the status of a RabbitMQ node after Nova components' boot 5. scheduler.phantom (phantom is hostname) 6. scheduler -.. image:: ../images/rpc/state.png +.. image:: ./images/rpc/state.png :width: 60% .. diff --git a/doc/source/devref/services.rst b/doc/source/services.rst similarity index 100% rename from doc/source/devref/services.rst rename to doc/source/services.rst diff --git a/doc/source/devref/testing/libvirt-numa.rst b/doc/source/testing/libvirt-numa.rst similarity index 100% rename from doc/source/devref/testing/libvirt-numa.rst rename to doc/source/testing/libvirt-numa.rst diff --git a/doc/source/devref/testing/serial-console.rst b/doc/source/testing/serial-console.rst similarity index 100% rename from doc/source/devref/testing/serial-console.rst rename to doc/source/testing/serial-console.rst diff --git a/doc/source/devref/threading.rst b/doc/source/threading.rst similarity index 100% rename from doc/source/devref/threading.rst rename to doc/source/threading.rst diff --git a/doc/source/devref/unit_tests.rst b/doc/source/unit_tests.rst similarity index 100% rename from doc/source/devref/unit_tests.rst rename to doc/source/unit_tests.rst diff --git a/doc/source/devref/upgrade.rst b/doc/source/upgrade.rst similarity index 100% rename from doc/source/devref/upgrade.rst rename to doc/source/upgrade.rst diff --git a/doc/source/devref/vmstates.rst b/doc/source/vmstates.rst similarity index 96% rename from doc/source/devref/vmstates.rst rename to doc/source/vmstates.rst index 38e136501e14..2b05ee069762 100644 --- a/doc/source/devref/vmstates.rst +++ b/doc/source/vmstates.rst @@ -172,9 +172,9 @@ task states for various commands issued by the user: shelved_offloaded -> unshelve } -.. image:: ../images/PowerStates1.png +.. image:: ./images/PowerStates1.png -.. image:: ../images/PowerStates2.png +.. image:: ./images/PowerStates2.png Create instance states @@ -184,4 +184,4 @@ The following diagram shows the sequence of VM states, task states, and power states when a new VM instance is created. -.. image:: ../images/run_instance_walkthrough.png +.. image:: ./images/run_instance_walkthrough.png