From a23cd43abe799af1b72b14c786f2fc9dbd8d3ec4 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Fri, 16 Jun 2017 05:05:06 +0900 Subject: [PATCH] docs: reorganize developer reference for new theme openstackdocstheme generates the toc tree in the left sidebar based on the page hierarchy from the top page. The previous developer guide hirarchy is a bit deep, and this commit reorganizes the devref pages for better navigation with openstackdocstheme. Change-Id: I1412b047efc1c268b34ef97e78073da7bcbb6d7e --- TESTING.rst | 1 + doc/source/devref/development.environment.rst | 4 +- doc/source/devref/index.rst | 71 +------------------ doc/source/devref/modules.rst | 36 ++++++++++ doc/source/devref/neutron_internals.rst | 63 ++++++++++++++++ doc/source/devref/testing.rst | 26 +++++++ doc/source/devref/testing_index.rst | 37 ++++++++++ doc/source/feature_classification/index.rst | 10 +-- doc/source/index.rst | 6 +- 9 files changed, 173 insertions(+), 81 deletions(-) create mode 100644 doc/source/devref/modules.rst create mode 100644 doc/source/devref/neutron_internals.rst create mode 100644 doc/source/devref/testing.rst create mode 100644 doc/source/devref/testing_index.rst diff --git a/TESTING.rst b/TESTING.rst index 34d62b1b481..70a1d677952 100644 --- a/TESTING.rst +++ b/TESTING.rst @@ -20,6 +20,7 @@ ''''''' Heading 4 (Avoid deeper levels because they do not render well.) +.. _testing_neutron: Testing Neutron =============== diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst index 4a74e120be8..9a73e537263 100644 --- a/doc/source/devref/development.environment.rst +++ b/doc/source/devref/development.environment.rst @@ -55,5 +55,7 @@ Grab the code:: git clone git://git.openstack.org/openstack/neutron.git cd neutron +Testing Neutron +--------------- -.. include:: ../../../TESTING.rst +See :ref:`testing_neutron`. diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 9a375d3b3fc..a860785f40a 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -33,11 +33,8 @@ including its database, message queue, and scheduler components. There are also subsections that describe specific plugins inside Neutron. Finally, the developer guide includes information about Neutron testing infrastructure. - -Programming HowTos and Tutorials --------------------------------- .. toctree:: - :maxdepth: 3 + :maxdepth: 2 effective_neutron development.environment @@ -45,68 +42,4 @@ Programming HowTos and Tutorials neutron_api client_command_extensions alembic_migrations - - -Neutron Internals ------------------ -.. toctree:: - :maxdepth: 3 - - services_and_agents - api_layer - ml2_ext_manager - calling_ml2_plugin - quota - api_extensions - plugin-api - db_layer - db_models - policy - rpc_api - rpc_callbacks - layer3 - l2_agents - agent_extensions - ovs_vhostuser - quality_of_service - service_extensions - dns_order - external_dns_integration - upgrade - objects_usage - i18n - address_scopes - openvswitch_firewall - network_ip_availability - tag - provisioning_blocks - retries - l3_agent_extensions - live_migration - -Testing -------- -.. toctree:: - :maxdepth: 3 - - fullstack_testing - testing_coverage - template_model_sync_test - db_transient_failure_injection - -Module Reference ----------------- -.. toctree:: - :maxdepth: 3 - -.. todo:: - - Add in all the big modules as automodule indexes. - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + modules diff --git a/doc/source/devref/modules.rst b/doc/source/devref/modules.rst new file mode 100644 index 00000000000..1afca028c61 --- /dev/null +++ b/doc/source/devref/modules.rst @@ -0,0 +1,36 @@ +.. + 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. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Module Reference +================ + +.. toctree:: + :maxdepth: 3 + +.. todo:: + + Add in all the big modules as automodule indexes. + diff --git a/doc/source/devref/neutron_internals.rst b/doc/source/devref/neutron_internals.rst new file mode 100644 index 00000000000..edc2f8424c9 --- /dev/null +++ b/doc/source/devref/neutron_internals.rst @@ -0,0 +1,63 @@ +.. + 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. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + +================= +Neutron Internals +================= + +.. toctree:: + :maxdepth: 1 + + services_and_agents + api_layer + ml2_ext_manager + calling_ml2_plugin + quota + api_extensions + plugin-api + db_layer + db_models + policy + rpc_api + rpc_callbacks + layer3 + l2_agents + agent_extensions + ovs_vhostuser + quality_of_service + service_extensions + dns_order + external_dns_integration + upgrade + objects_usage + i18n + address_scopes + openvswitch_firewall + network_ip_availability + tag + provisioning_blocks + retries + l3_agent_extensions + live_migration diff --git a/doc/source/devref/testing.rst b/doc/source/devref/testing.rst new file mode 100644 index 00000000000..340374413e1 --- /dev/null +++ b/doc/source/devref/testing.rst @@ -0,0 +1,26 @@ +.. + 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. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + +.. include:: ../../../TESTING.rst diff --git a/doc/source/devref/testing_index.rst b/doc/source/devref/testing_index.rst new file mode 100644 index 00000000000..64a52aba1ca --- /dev/null +++ b/doc/source/devref/testing_index.rst @@ -0,0 +1,37 @@ +.. + 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. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + +======= +Testing +======= + +.. toctree:: + :maxdepth: 2 + + testing + fullstack_testing + testing_coverage + template_model_sync_test + db_transient_failure_injection diff --git a/doc/source/feature_classification/index.rst b/doc/source/feature_classification/index.rst index b3fb5e7c2b5..df0778cb3a3 100644 --- a/doc/source/feature_classification/index.rst +++ b/doc/source/feature_classification/index.rst @@ -28,16 +28,8 @@ Neutron Feature Classification ============================== .. toctree:: - :maxdepth: 3 + :maxdepth: 2 feature_classification_introduction general_feature_support_matrix provider_network_support_matrix - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/source/index.rst b/doc/source/index.rst index f5805c64c94..18223433e27 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -59,7 +59,7 @@ Neutron Feature Classification ------------------------------ .. toctree:: - :maxdepth: 3 + :maxdepth: 2 feature_classification/index @@ -67,9 +67,11 @@ Developer Docs -------------- .. toctree:: - :maxdepth: 3 + :maxdepth: 2 devref/index + devref/testing_index + devref/neutron_internals Dashboards ----------