From 2925105d0f6231c24eec5754ca2b4e0df7294ff4 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 5 Feb 2018 15:15:34 +0000 Subject: [PATCH] doc: Start using openstackdoctheme's extlink extension This ensures we have version-specific references to other projects [1]. Note that this doesn't mean the URLs are actually valid - we need to do more work (linkcheck?) here, but it's an improvement nonetheless. [1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper Change-Id: Ifb99e727110c4904a85bc4a13366c2cae300b8df --- doc/requirements.txt | 2 +- doc/source/conf.py | 21 +++++++++ doc/source/contributor/placement.rst | 15 +++---- doc/source/index.rst | 43 ++++++++----------- doc/source/install/controller-install-obs.rst | 8 ++-- doc/source/install/controller-install-rdo.rst | 7 ++- .../install/controller-install-ubuntu.rst | 8 ++-- placement-api-ref/source/conf.py | 6 +++ placement-api-ref/source/index.rst | 4 +- 9 files changed, 66 insertions(+), 48 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 77fc36cae..a6bb0d587 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,7 +5,7 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD sphinxcontrib-actdiag>=0.8.5 # BSD sphinxcontrib-seqdiag>=0.8.4 # BSD os-api-ref>=1.4.0 # Apache-2.0 -openstackdocstheme>=1.18.1 # Apache-2.0 +openstackdocstheme>=1.19.0 # Apache-2.0 # releasenotes reno>=2.5.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index 61d485040..b163e8d72 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -171,6 +171,27 @@ latex_documents = [ u'OpenStack Foundation', 'manual'), ] +# -- Options for openstackdocstheme ------------------------------------------- + +# keep this ordered to keep mriedem happy +openstack_projects = [ + 'ceilometer', + 'cinder', + 'glance', + 'horizon', + 'ironic', + 'keystone', + 'neutron', + 'nova', + 'oslo.log', + 'oslo.messaging', + 'oslo.i18n', + 'oslo.versionedobjects', + 'python-novaclient', + 'python-openstackclient', + 'reno', + 'watcher', +] # -- Custom extensions -------------------------------------------------------- diff --git a/doc/source/contributor/placement.rst b/doc/source/contributor/placement.rst index 12773d1dd..faa282048 100644 --- a/doc/source/contributor/placement.rst +++ b/doc/source/contributor/placement.rst @@ -40,10 +40,11 @@ increasing the number of WSGI application instances and scaling the RDBMS using traditional database scaling techniques. For sake of consistency and because there was initially intent to make the -entities in the placement service available over RPC, `versioned objects`_ are -used to provide the interface between the HTTP application layer and the -SQLAlchemy-driven persistence layer. Even without RPC, these objects provide -useful structuring and separation of the code. +entities in the placement service available over RPC, +:oslo.versionedobjects-doc:`versioned objects <>` are used to provide the +interface between the HTTP application layer and the SQLAlchemy-driven +persistence layer. Even without RPC, these objects provide useful structuring +and separation of the code. Though the placement service doesn't aspire to be a `microservice` it does aspire to continue to be small and minimally complex. This means a relatively @@ -145,8 +146,8 @@ there are a few bits of required housekeeping that must be done in the code: microversion and give a very brief summary of the added feature. * Update ``nova/api/openstack/placement/rest_api_version_history.rst`` to add a more detailed section describing the new microversion. -* Add a `release note`_ with a ``features`` section announcing the new or - changed feature and the microversion. +* Add a :reno-doc:`release note <>` with a ``features`` section announcing the + new or changed feature and the microversion. * If the ``version_handler`` decorator (see below) has been used, increment ``TOTAL_VERSIONED_METHODS`` in ``nova/tests/unit/api/openstack/placement/test_microversion.py``. @@ -413,13 +414,11 @@ When creating new code for the placement service, please be aware of the plan for an eventual extraction and avoid creating unnecessary interdependencies. .. _WSGI: https://www.python.org/dev/peps/pep-3333/ -.. _versioned objects: http://docs.openstack.org/developer/oslo.versionedobjects/ .. _wsgify: http://docs.webob.org/en/latest/api/dec.html .. _WebOb: http://docs.webob.org/en/latest/ .. _Request: http://docs.webob.org/en/latest/reference.html#request .. _Response: http://docs.webob.org/en/latest/#response .. _microversions: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html -.. _release note: https://docs.openstack.org/reno/latest/user/usage.html .. _gabbi: https://gabbi.readthedocs.io/ .. _telemetry: http://specs.openstack.org/openstack/telemetry-specs/specs/kilo/declarative-http-tests.html .. _wsgi-intercept: http://wsgi-intercept.readthedocs.io/ diff --git a/doc/source/index.rst b/doc/source/index.rst index 5600286dc..da7058975 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -30,13 +30,12 @@ servers to provide that service. It requires the following additional OpenStack services for basic function: -* `Keystone `__: This provides - identity and authentication for all OpenStack services. -* `Glance `__: This provides the - compute image repository. All compute instances launch from glance images. -* `Neutron `__: This is - responsible for provisioning the virtual or physical networks that compute - instances connect to on boot. +* :keystone-doc:`Keystone <>`: This provides identity and authentication for + all OpenStack services. +* :glance-doc:`Glance <>`: This provides the compute image repository. All + compute instances launch from glance images. +* :neutron-doc:`Neutron <>`: This is responsible for provisioning the virtual + or physical networks that compute instances connect to on boot. It can also integrate with other services to include: persistent block storage, encrypted disks, and baremetal compute instances. @@ -50,19 +49,15 @@ either tools or the API directly. Tools for using Nova -------------------- -* `Horizon - `_: The - official web ui for the OpenStack Project. -* `OpenStack Client - `_: The official - CLI for OpenStack Projects. You should use this as your CLI for most things, - it includes not just nova commands but also commands for most of the projects - in OpenStack. -* `Nova Client - `_: For - some very advanced features (or administrative commands) of nova you may need - to use nova client. It is still supported, but the ``openstack`` cli is - recommended. +* :horizon-doc:`Horizon `: The official web UI for + the OpenStack Project. +* :python-openstackclient-doc:`OpenStack Client <>`: The official CLI for + OpenStack Projects. You should use this as your CLI for most things, it + includes not just nova commands but also commands for most of the projects in + OpenStack. +* :python-novaclient-doc:`Nova Client `: For some very + advanced features (or administrative commands) of nova you may need to use + nova client. It is still supported, but the ``openstack`` cli is recommended. Writing to the API ------------------ @@ -117,11 +112,9 @@ Installation .. TODO(sdague): links to all the rest of the install guide pieces. The detailed install guide for nova. A functioning nova will also require -having installed `keystone -`__, `glance -`__, and `neutron -`__. Please ensure that you -follow their install guides first. +having installed :keystone-doc:`keystone `, :glance-doc:`glance +`, and :neutron-doc:`neutron `. Ensure that you follow +their install guides first. .. toctree:: :maxdepth: 2 diff --git a/doc/source/install/controller-install-obs.rst b/doc/source/install/controller-install-obs.rst index cd70061e0..3c630bc1f 100644 --- a/doc/source/install/controller-install-obs.rst +++ b/doc/source/install/controller-install-obs.rst @@ -379,10 +379,10 @@ Install and configure components Compute firewall driver by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall driver. - * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the - `Networking service install guide`__ for more details. - - .. __: https://docs.openstack.org/neutron/latest/install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service + * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to + the :neutron-doc:`Networking service install guide + ` + for more details. * In the ``[vnc]`` section, configure the VNC proxy to use the management interface IP address of the controller node: diff --git a/doc/source/install/controller-install-rdo.rst b/doc/source/install/controller-install-rdo.rst index 92174761a..9792fc797 100644 --- a/doc/source/install/controller-install-rdo.rst +++ b/doc/source/install/controller-install-rdo.rst @@ -369,10 +369,9 @@ Install and configure components Compute firewall driver by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall driver. - * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the - `Networking service install guide`__ for more details. - - .. __: https://docs.openstack.org/neutron/latest/install/controller-install-rdo.html#configure-the-compute-service-to-use-the-networking-service + * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to + the :neutron-doc:`Networking service install guide + ` for more details. * In the ``[vnc]`` section, configure the VNC proxy to use the management interface IP address of the controller node: diff --git a/doc/source/install/controller-install-ubuntu.rst b/doc/source/install/controller-install-ubuntu.rst index 3d6b1b04a..c2f253aef 100644 --- a/doc/source/install/controller-install-ubuntu.rst +++ b/doc/source/install/controller-install-ubuntu.rst @@ -359,10 +359,10 @@ Install and configure components Compute firewall driver by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall driver. - * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the - `Networking service install guide`__ for more details. - - .. __: https://docs.openstack.org/neutron/latest/install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service + * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to + the :neutron-doc:`Networking service install guide + ` + for more information. * In the ``[vnc]`` section, configure the VNC proxy to use the management interface IP address of the controller node: diff --git a/placement-api-ref/source/conf.py b/placement-api-ref/source/conf.py index 536f02cdd..f52d3fdbd 100644 --- a/placement-api-ref/source/conf.py +++ b/placement-api-ref/source/conf.py @@ -88,3 +88,9 @@ latex_documents = [ ('index', 'Placement.tex', u'OpenStack Placement API Documentation', u'OpenStack Foundation', 'manual'), ] + +# -- Options for openstackdocstheme ------------------------------------------- + +openstack_projects = [ + 'nova', +] diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst index fe0feee27..d09315b8e 100644 --- a/placement-api-ref/source/index.rst +++ b/placement-api-ref/source/index.rst @@ -5,8 +5,8 @@ =============== This is a reference for the OpenStack Placement API. To learn more about -OpenStack Placement API concepts, please refer to the -`Placement Introduction `_. +OpenStack Placement API concepts, please refer to the :nova-doc:`Placement +Introduction `. The Placement API uses JSON for data exchange. As such, the ``Content-Type`` header for APIs sending data payloads in the request body (i.e. ``PUT`` and