From 5647bfc246a4363f65fc2b95bc7b3b9b138bc045 Mon Sep 17 00:00:00 2001 From: Sam Betts Date: Mon, 3 Jul 2017 16:34:42 +0100 Subject: [PATCH] Move doc/source/dev to doc/source/contributor Change-Id: I6a3d143cff31348c62d8825f29f7484bafb9c8f0 --- .gitignore | 2 +- .../baremetal-api-v1-node-management.inc | 2 +- .../source/samples/api-v1-root-response.json | 2 +- .../{dev => contributor}/architecture.rst | 8 +- .../code-contribution-guide.rst | 0 .../{dev => contributor}/dev-quickstart.rst | 0 doc/source/{dev => contributor}/drivers.rst | 0 doc/source/{dev => contributor}/faq.rst | 0 .../{dev => contributor}/governance.rst | 0 doc/source/contributor/index.rst | 86 ++++++++++++++++++ .../ironic-multitenant-networking.rst | 0 .../{dev => contributor}/notifications.rst | 0 doc/source/{dev => contributor}/releasing.rst | 4 +- doc/source/{dev => contributor}/states.rst | 0 .../{dev => contributor}/third-party-ci.rst | 0 .../{dev => contributor}/vendor-passthru.rst | 0 .../webapi-version-history.rst | 0 doc/source/{dev => contributor}/webapi.rst | 0 doc/source/index.rst | 87 ++----------------- doc/source/install/enabling-drivers.rst | 2 +- doc/source/install/enrollment.rst | 2 +- doc/source/webapi/v1.rst | 5 -- ironic/api/controllers/v1/__init__.py | 2 +- setup.cfg | 1 + 24 files changed, 107 insertions(+), 96 deletions(-) rename doc/source/{dev => contributor}/architecture.rst (95%) rename doc/source/{dev => contributor}/code-contribution-guide.rst (100%) rename doc/source/{dev => contributor}/dev-quickstart.rst (100%) rename doc/source/{dev => contributor}/drivers.rst (100%) rename doc/source/{dev => contributor}/faq.rst (100%) rename doc/source/{dev => contributor}/governance.rst (100%) create mode 100644 doc/source/contributor/index.rst rename doc/source/{dev => contributor}/ironic-multitenant-networking.rst (100%) rename doc/source/{dev => contributor}/notifications.rst (100%) rename doc/source/{dev => contributor}/releasing.rst (95%) rename doc/source/{dev => contributor}/states.rst (100%) rename doc/source/{dev => contributor}/third-party-ci.rst (100%) rename doc/source/{dev => contributor}/vendor-passthru.rst (100%) rename doc/source/{dev => contributor}/webapi-version-history.rst (100%) rename doc/source/{dev => contributor}/webapi.rst (100%) delete mode 100644 doc/source/webapi/v1.rst diff --git a/.gitignore b/.gitignore index 5fd6382be8..df0ae40bf9 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ # Sphinx _build -doc/source/api/ +doc/source/contributor/api/ # release notes build releasenotes/build diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc index 493139b5dc..38341fff7b 100644 --- a/api-ref/source/baremetal-api-v1-node-management.inc +++ b/api-ref/source/baremetal-api-v1-node-management.inc @@ -331,7 +331,7 @@ Request a change to the Node's provision state. Acceptable target states depend on the Node's current provision state. More detailed documentation of the Ironic State Machine is available -`in the developer docs `_. +`in the developer docs `_. Normal response code: 202 diff --git a/api-ref/source/samples/api-v1-root-response.json b/api-ref/source/samples/api-v1-root-response.json index 0a0a11a2f5..e2841bc4aa 100644 --- a/api-ref/source/samples/api-v1-root-response.json +++ b/api-ref/source/samples/api-v1-root-response.json @@ -36,7 +36,7 @@ "rel": "self" }, { - "href": "https://docs.openstack.org/developer/ironic/dev/webapi.html", + "href": "https://docs.openstack.org/ironic/latest/contributor/webapi.html", "rel": "describedby", "type": "text/html" } diff --git a/doc/source/dev/architecture.rst b/doc/source/contributor/architecture.rst similarity index 95% rename from doc/source/dev/architecture.rst rename to doc/source/contributor/architecture.rst index db08c47369..1089046034 100644 --- a/doc/source/dev/architecture.rst +++ b/doc/source/contributor/architecture.rst @@ -112,10 +112,10 @@ cluster, nodes may be remapped to different Conductors, thus triggering various driver actions such as take-over or clean-up. -.. _API service: ../webapi/v1.html -.. _BaseDriver: ../api/ironic.drivers.base.html#ironic.drivers.base.BaseDriver -.. _Conductor service: ../api/ironic.conductor.manager.html -.. _DB API: ../api/ironic.db.api.html +.. _API service: webapi.html +.. _BaseDriver: api/ironic.drivers.base.html#ironic.drivers.base.BaseDriver +.. _Conductor service: api/ironic.conductor.manager.html +.. _DB API: api/ironic.db.api.html .. _diskimage-builder: http://docs.openstack.org/developer/diskimage-builder/ .. _consistent hashing algorithm: http://docs.openstack.org/developer/tooz/tutorial/hashring.html .. _periodic: http://docs.openstack.org/developer/futurist/api.html#futurist.periodics.periodic diff --git a/doc/source/dev/code-contribution-guide.rst b/doc/source/contributor/code-contribution-guide.rst similarity index 100% rename from doc/source/dev/code-contribution-guide.rst rename to doc/source/contributor/code-contribution-guide.rst diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/contributor/dev-quickstart.rst similarity index 100% rename from doc/source/dev/dev-quickstart.rst rename to doc/source/contributor/dev-quickstart.rst diff --git a/doc/source/dev/drivers.rst b/doc/source/contributor/drivers.rst similarity index 100% rename from doc/source/dev/drivers.rst rename to doc/source/contributor/drivers.rst diff --git a/doc/source/dev/faq.rst b/doc/source/contributor/faq.rst similarity index 100% rename from doc/source/dev/faq.rst rename to doc/source/contributor/faq.rst diff --git a/doc/source/dev/governance.rst b/doc/source/contributor/governance.rst similarity index 100% rename from doc/source/dev/governance.rst rename to doc/source/contributor/governance.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000000..5f5d993ac5 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,86 @@ +Developer's Guide +================= + +Getting Started +--------------- + +If you are new to ironic, this section contains information that should help +you get started as a developer working on the project or contributing to the +project. + +.. toctree:: + :maxdepth: 1 + + Developer Contribution Guide + Setting Up Your Development Environment + Frequently Asked Questions + +The following pages describe the architecture of the Bare Metal service +and may be helpful to anyone working on or with the service, but are written +primarily for developers. + +.. toctree:: + :maxdepth: 1 + + Ironic System Architecture + Provisioning State Machine + Developing New Notifications + +These pages contain information for PTLs, cross-project liaisons, and core +reviewers. + +.. toctree:: + :maxdepth: 1 + + Releasing Ironic Projects + Ironic Governance Structure + + +Writing Drivers +--------------- + +Ironic's community includes many hardware vendors who contribute drivers that +enable more advanced functionality when Ironic is used in conjunction with that +hardware. To do this, the Ironic developer community is committed to +standardizing on a `Python Driver API `_ that +meets the common needs of all hardware vendors, and evolving this API without +breaking backwards compatibility. However, it is sometimes necessary for driver +authors to implement functionality - and expose it through the REST API - that +can not be done through any existing API. + +To facilitate that, we also provide the means for API calls to be "passed +through" ironic and directly to the driver. Some guidelines on how to implement +this are provided below. Driver authors are strongly encouraged to talk with +the developer community about any implementation using this functionality. + +.. toctree:: + :maxdepth: 1 + + Driver Overview + Driver Base Class Definition + Writing "vendor_passthru" methods + Third party continuous integration testing + +Testing Network Integration +--------------------------- + +In order to test the integration between the Bare Metal and Networking +services, support has been added to `devstack `_ +to mimic an external physical switch. Here we include a recommended +configuration for devstack to bring up this environment. + +.. toctree:: + :maxdepth: 1 + + Configuring Devstack for multitenant network testing + +Full Ironic Server Python API Reference +--------------------------------------- + +* :ref:`modindex` + +.. # api/autoindex is hidden since it's in the modindex link above. +.. toctree:: + :hidden: + + api/autoindex diff --git a/doc/source/dev/ironic-multitenant-networking.rst b/doc/source/contributor/ironic-multitenant-networking.rst similarity index 100% rename from doc/source/dev/ironic-multitenant-networking.rst rename to doc/source/contributor/ironic-multitenant-networking.rst diff --git a/doc/source/dev/notifications.rst b/doc/source/contributor/notifications.rst similarity index 100% rename from doc/source/dev/notifications.rst rename to doc/source/contributor/notifications.rst diff --git a/doc/source/dev/releasing.rst b/doc/source/contributor/releasing.rst similarity index 95% rename from doc/source/dev/releasing.rst rename to doc/source/contributor/releasing.rst index d31e69f512..823f765b36 100644 --- a/doc/source/dev/releasing.rst +++ b/doc/source/contributor/releasing.rst @@ -40,7 +40,7 @@ Things to do before releasing * For ironic releases only, not ironic-inspector releases: if any new API microversions have been added since the last release, update the REST API - version history (doc/source/dev/webapi-version-history.rst) to + version history (doc/source/contributor/webapi-version-history.rst) to indicate that they were part of the new release. * To support rolling upgrades, add this new release version (and release name @@ -54,7 +54,7 @@ Things to do before releasing * Regenerate the sample config file, so that the choices for the ``[DEFAULT]/pin_release_version`` configuration are accurate. -.. _`standards`: http://docs.openstack.org/developer/ironic/dev/faq.html#know-if-a-release-note-is-needed-for-my-change +.. _`standards`: http://docs.openstack.org/ironic/latest/contributor/faq.html#know-if-a-release-note-is-needed-for-my-change Things to do after releasing ============================ diff --git a/doc/source/dev/states.rst b/doc/source/contributor/states.rst similarity index 100% rename from doc/source/dev/states.rst rename to doc/source/contributor/states.rst diff --git a/doc/source/dev/third-party-ci.rst b/doc/source/contributor/third-party-ci.rst similarity index 100% rename from doc/source/dev/third-party-ci.rst rename to doc/source/contributor/third-party-ci.rst diff --git a/doc/source/dev/vendor-passthru.rst b/doc/source/contributor/vendor-passthru.rst similarity index 100% rename from doc/source/dev/vendor-passthru.rst rename to doc/source/contributor/vendor-passthru.rst diff --git a/doc/source/dev/webapi-version-history.rst b/doc/source/contributor/webapi-version-history.rst similarity index 100% rename from doc/source/dev/webapi-version-history.rst rename to doc/source/contributor/webapi-version-history.rst diff --git a/doc/source/dev/webapi.rst b/doc/source/contributor/webapi.rst similarity index 100% rename from doc/source/dev/webapi.rst rename to doc/source/contributor/webapi.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index a77642810a..b8b5de0ce5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,87 +45,19 @@ guide as well as more detailed reference documentation. .. toctree:: :maxdepth: 1 - API Concept Guide + API Concept Guide API Reference (latest) - API Version History + API Reference (latest) + API Version History -Developer's Guide -================= - -Getting Started ---------------- - -If you are new to ironic, this section contains information that should help -you get started as a developer working on the project or contributing to the -project. +Contributor's Guide +=================== .. toctree:: - :maxdepth: 1 - - Developer Contribution Guide - Setting Up Your Development Environment - Frequently Asked Questions - -The following pages describe the architecture of the Bare Metal service -and may be helpful to anyone working on or with the service, but are written -primarily for developers. - -.. toctree:: - :maxdepth: 1 - - Ironic System Architecture - Provisioning State Machine - Developing New Notifications - -These pages contain information for PTLs, cross-project liaisons, and core -reviewers. - -.. toctree:: - :maxdepth: 1 - - Releasing Ironic Projects - Ironic Governance Structure - - -Writing Drivers ---------------- - -Ironic's community includes many hardware vendors who contribute drivers that -enable more advanced functionality when Ironic is used in conjunction with that -hardware. To do this, the Ironic developer community is committed to -standardizing on a `Python Driver API `_ that -meets the common needs of all hardware vendors, and evolving this API without -breaking backwards compatibility. However, it is sometimes necessary for driver -authors to implement functionality - and expose it through the REST API - that -can not be done through any existing API. - -To facilitate that, we also provide the means for API calls to be "passed -through" ironic and directly to the driver. Some guidelines on how to implement -this are provided below. Driver authors are strongly encouraged to talk with -the developer community about any implementation using this functionality. - -.. toctree:: - :maxdepth: 1 - - Driver Overview - Driver Base Class Definition - Writing "vendor_passthru" methods - Third party continuous integration testing - -Testing Network Integration ---------------------------- - -In order to test the integration between the Bare Metal and Networking -services, support has been added to `devstack `_ -to mimic an external physical switch. Here we include a recommended -configuration for devstack to bring up this environment. - -.. toctree:: - :maxdepth: 1 - - Configuring Devstack for multitenant network testing + :maxdepth: 2 + contributor/index Administrator's Guide ===================== @@ -161,17 +93,14 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` .. # NOTE(jaegerandi): This is where we hide things that we don't want - # shown in the top level table of contents. api/autoindex is hidden - # since it's in the modindex link above. + # shown in the top level table of contents. # user/index is referenced above but not in a toctree. .. toctree:: :hidden: - api/autoindex admin/install-guide.rst user/index releasenotes/index diff --git a/doc/source/install/enabling-drivers.rst b/doc/source/install/enabling-drivers.rst index 097f80feb3..5b5e20fc24 100644 --- a/doc/source/install/enabling-drivers.rst +++ b/doc/source/install/enabling-drivers.rst @@ -290,4 +290,4 @@ See `driver-specific documentation`_ for required configuration of each driver. .. _ironic-inspector: https://docs.openstack.org/developer/ironic-inspector/ .. _inspection documentation: https://docs.openstack.org/ironic/latest/admin/inspection.html .. _RAID documentation: https://docs.openstack.org/ironic/latest/admin/raid.html -.. _vendor methods documentation: https://docs.openstack.org/developer/ironic/dev/vendor-passthru.html +.. _vendor methods documentation: https://docs.openstack.org/ironic/latest/contributor/vendor-passthru.html diff --git a/doc/source/install/enrollment.rst b/doc/source/install/enrollment.rst index 138baf01b2..d9bfbb6047 100644 --- a/doc/source/install/enrollment.rst +++ b/doc/source/install/enrollment.rst @@ -449,7 +449,7 @@ To move a node from ``manageable`` to ``available`` provision state: +------------------------+--------------------------------------------------------------------+ For more details on the Bare Metal service's state machine, see the -`state machine `_ +`state machine `_ documentation. .. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter diff --git a/doc/source/webapi/v1.rst b/doc/source/webapi/v1.rst deleted file mode 100644 index c086b60057..0000000000 --- a/doc/source/webapi/v1.rst +++ /dev/null @@ -1,5 +0,0 @@ -======== -REST API -======== - -The API documentation reference `has been moved here <../dev/webapi.html>`_. diff --git a/ironic/api/controllers/v1/__init__.py b/ironic/api/controllers/v1/__init__.py index 431b89840d..e2ac631a3e 100644 --- a/ironic/api/controllers/v1/__init__.py +++ b/ironic/api/controllers/v1/__init__.py @@ -102,7 +102,7 @@ class V1(base.APIBase): 'v1', '', bookmark=True), link.Link.make_link('describedby', 'https://docs.openstack.org', - 'developer/ironic/dev', + '/ironic/latest/contributor/', 'webapi.html', bookmark=True, type='text/html') ] diff --git a/setup.cfg b/setup.cfg index a55e8e2878..dee4b5cce0 100644 --- a/setup.cfg +++ b/setup.cfg @@ -166,6 +166,7 @@ autodoc_exclude_modules = ironic.db.sqlalchemy.alembic.env ironic.db.sqlalchemy.alembic.versions.* ironic_tempest_plugin.* +api_doc_dir = contributor/api [build_sphinx] all_files = 1