diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 00955b1..d48fa13 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,17 +1,14 @@ If you would like to contribute to the development of OpenStack, you must follow the steps in this page: - - http://docs.openstack.org/infra/manual/developers.html +http://docs.openstack.org/infra/manual/developers.html If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool: - - http://docs.openstack.org/infra/manual/developers.html#development-workflow +http://docs.openstack.org/infra/manual/developers.html#development-workflow Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/neutron-lib +https://bugs.launchpad.net/neutron-lib diff --git a/doc/source/devref/api_attributes.rst b/doc/source/contributor/api_attributes.rst similarity index 100% rename from doc/source/devref/api_attributes.rst rename to doc/source/contributor/api_attributes.rst diff --git a/doc/source/devref/api_converters.rst b/doc/source/contributor/api_converters.rst similarity index 100% rename from doc/source/devref/api_converters.rst rename to doc/source/contributor/api_converters.rst diff --git a/doc/source/devref/api_extensions.rst b/doc/source/contributor/api_extensions.rst similarity index 100% rename from doc/source/devref/api_extensions.rst rename to doc/source/contributor/api_extensions.rst diff --git a/doc/source/devref/api_validators.rst b/doc/source/contributor/api_validators.rst similarity index 100% rename from doc/source/devref/api_validators.rst rename to doc/source/contributor/api_validators.rst diff --git a/doc/source/devref/callbacks.rst b/doc/source/contributor/callbacks.rst similarity index 100% rename from doc/source/devref/callbacks.rst rename to doc/source/contributor/callbacks.rst diff --git a/doc/source/contributing.rst b/doc/source/contributor/contributing.rst similarity index 63% rename from doc/source/contributing.rst rename to doc/source/contributor/contributing.rst index 9d95af6..ef6b614 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -1,7 +1,8 @@ ============ Contributing ============ -.. include:: ../../CONTRIBUTING.rst + +.. include:: ../../../CONTRIBUTING.rst As your code is subject to the `review guidelines <./review-guidelines.html>`_, please take the time to familiarize yourself with those guidelines. @@ -25,50 +26,50 @@ The rehoming workflow procedure has four main phases: Phase 1: Rehome ~~~~~~~~~~~~~~~ - #. Identify the chunk of code for rehoming. Applicable code includes common - classes/functions/modules/etc. that are consumed by networking project(s) outside of - neutron. Optimal consumption patterns of the code at hand must also be considered to - ensure the rehomed code addresses any technical debt. Finally, leave low-hanging - fruit for last and tackle the most commonly used code first. If you have any doubt - about the applicability of code for rehoming, reach out to one of the neutron core - developers before digging in. +#. Identify the chunk of code for rehoming. Applicable code includes common + classes/functions/modules/etc. that are consumed by networking project(s) outside of + neutron. Optimal consumption patterns of the code at hand must also be considered to + ensure the rehomed code addresses any technical debt. Finally, leave low-hanging + fruit for last and tackle the most commonly used code first. If you have any doubt + about the applicability of code for rehoming, reach out to one of the neutron core + developers before digging in. - #. Find and identify any unit tests for the code being rehomed. These unit tests - can often be moved into neutron-lib with minimal effort. After inspecting the - applicable unit tests, rewrite any that are non-optimal. +#. Find and identify any unit tests for the code being rehomed. These unit tests + can often be moved into neutron-lib with minimal effort. After inspecting the + applicable unit tests, rewrite any that are non-optimal. - #. Search and understand the consumers of the code being rehomed. This must include other - networking projects in addition to neutron itself. At this point it may be determined - that the code should be refactored before it is consumed. There are a few common - strategies for refactoring, and the one chosen will depend on the nature of the code - at hand: +#. Search and understand the consumers of the code being rehomed. This must include other + networking projects in addition to neutron itself. At this point it may be determined + that the code should be refactored before it is consumed. There are a few common + strategies for refactoring, and the one chosen will depend on the nature of the code + at hand: - - Refactor/enhance the code as part of the initial neutron-lib patch. If this change - will be disruptive to consumers, clearly communicate the change via email list or - `meeting topic `_. - - Leave the refactoring to the next (Enhance) phase. In this rehome phase, copy the code - as-is into a private module according to our `conventions <./conventions.html>`_. This - approach is slower, but may be necessary in some cases. + - Refactor/enhance the code as part of the initial neutron-lib patch. If this change + will be disruptive to consumers, clearly communicate the change via email list or + `meeting topic `_. + - Leave the refactoring to the next (Enhance) phase. In this rehome phase, copy the code + as-is into a private module according to our `conventions <./conventions.html>`_. This + approach is slower, but may be necessary in some cases. - #. Understand existing work underway which may impact the rehomed code, for example, - in-flight patch sets that update the code being rehomed. In some cases it may make - sense to let the in-flight patch merge and solidify a bit before rehoming. +#. Understand existing work underway which may impact the rehomed code, for example, + in-flight patch sets that update the code being rehomed. In some cases it may make + sense to let the in-flight patch merge and solidify a bit before rehoming. - #. Prepare the code for neutron-lib. This may require replacing existing imports - with those provided by neutron-lib and/or rewriting/rearchitecting non-optimal - code (see above). The interfaces in the rehomed code are subject to our - `conventions <./conventions.html>`_. +#. Prepare the code for neutron-lib. This may require replacing existing imports + with those provided by neutron-lib and/or rewriting/rearchitecting non-optimal + code (see above). The interfaces in the rehomed code are subject to our + `conventions <./conventions.html>`_. - #. Prepare the unit test code for neutron-lib. As indicated in the `review guidelines - <./review-guidelines.html>`_ we are looking for a high code coverage by tests. This may - require adding additional tests if neutron was lacking in coverage. +#. Prepare the unit test code for neutron-lib. As indicated in the `review guidelines + <./review-guidelines.html>`_ we are looking for a high code coverage by tests. This may + require adding additional tests if neutron was lacking in coverage. - #. Submit and shepherd your patch through its neutron-lib review. Include a - `release note `_ that describes the code's - old neutron location and new neutron-lib location. Also note that in some cases it makes - sense to prototype a change in a consumer project to better understand the impacts of - the change, which can be done using the ``Depends-On:`` approach described in the - `review guidelines <./review-guidelines.html>`_ +#. Submit and shepherd your patch through its neutron-lib review. Include a + `release note `_ that describes the code's + old neutron location and new neutron-lib location. Also note that in some cases it makes + sense to prototype a change in a consumer project to better understand the impacts of + the change, which can be done using the ``Depends-On:`` approach described in the + `review guidelines <./review-guidelines.html>`_ Examples: diff --git a/doc/source/conventions.rst b/doc/source/contributor/conventions.rst similarity index 100% rename from doc/source/conventions.rst rename to doc/source/contributor/conventions.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..9b4b4c9 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,36 @@ +.. + 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 lib 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.) + + +Contributor Guide +================= + +In the Contributor Guide, you will find information on the Neutron Library +components and in how to use them, from a development standpoint. + +.. toctree:: + :maxdepth: 2 + + conventions + review-guidelines + contributing + releasing + internals diff --git a/doc/source/devref/index.rst b/doc/source/contributor/internals.rst similarity index 71% rename from doc/source/devref/index.rst rename to doc/source/contributor/internals.rst index 00ab2e7..8d22a23 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/contributor/internals.rst @@ -19,16 +19,10 @@ ''''''' Heading 4 (Avoid deeper levels because they do not render well.) - -Developer Guide -=============== - -In the Developer Guide, you will find information on the Neutron Library -components and in how to use them, from a development standpoint. - - +===================== Neutron Lib Internals ---------------------- +===================== + .. toctree:: :maxdepth: 3 @@ -37,20 +31,3 @@ Neutron Lib Internals api_converters api_validators callbacks - - -Module Reference ----------------- -.. toctree:: - :maxdepth: 3 - -.. todo:: - - Add in all the big modules as automodule indexes. - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`search` diff --git a/doc/source/releasing.rst b/doc/source/contributor/releasing.rst similarity index 100% rename from doc/source/releasing.rst rename to doc/source/contributor/releasing.rst diff --git a/doc/source/review-guidelines.rst b/doc/source/contributor/review-guidelines.rst similarity index 100% rename from doc/source/review-guidelines.rst rename to doc/source/contributor/review-guidelines.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index c6a4521..652bb05 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,8 +11,8 @@ License for the specific language governing permissions and limitations under the License. -Welcome to Neutron Lib developer documentation! -=============================================== +Welcome to Neutron Lib documentation! +===================================== Neutron-lib is an OpenStack library project used by Neutron, Advanced Services, and third-party projects that aims to provide common functionality across all @@ -39,24 +39,10 @@ The `Neutron Development wiki`_ is also a good resource for new contributors. Enjoy! - -Programming HowTos and Tutorials --------------------------------- .. toctree:: - :maxdepth: 3 + :maxdepth: 2 - conventions - installation - usage - review-guidelines - contributing - releasing - - -Developer Docs -============== - -.. toctree:: - :maxdepth: 1 - - devref/index + install/index + user/index + contributor/index + reference/index diff --git a/doc/source/installation.rst b/doc/source/install/index.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/install/index.rst diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..93aa723 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,34 @@ +.. + 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 lib 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: 1 + +.. todo:: + + Add in all the big modules as automodule indexes. + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/usage.rst b/doc/source/user/hacking.rst similarity index 96% rename from doc/source/usage.rst rename to doc/source/user/hacking.rst index fcf5805..0638443 100644 --- a/doc/source/usage.rst +++ b/doc/source/user/hacking.rst @@ -1,14 +1,6 @@ -======== -Usage -======== - -To use neutron-lib in a project:: - - import neutron_lib - - +============== Hacking Checks --------------- +============== The ``neutron_lib.hacking`` package implements a number of public `hacking checks `_ intended to help diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000..8eaebfc --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,8 @@ +===== +Usage +===== + +.. toctree:: + :maxdepth: 2 + + hacking