openstack/placement
Code Issues Proposed changes

doc: Start using openstackdoctheme's extlink extension

Browse Source 
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
This commit is contained in:
Stephen Finucane 2018-02-05 15:15:34 +00:00
parent 07d982aa1c
commit 2925105d0f
9 changed files with 66 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/requirements.txt
View File

@ -5,7 +5,7 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
sphinxcontrib-actdiag>=0.8.5 # BSD sphinxcontrib-actdiag>=0.8.5 # BSD
sphinxcontrib-seqdiag>=0.8.4 # BSD sphinxcontrib-seqdiag>=0.8.4 # BSD
os-api-ref>=1.4.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0 openstackdocstheme>=1.19.0 # Apache-2.0
# releasenotes # releasenotes
reno>=2.5.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0

21
doc/source/conf.py
View File

@ -171,6 +171,27 @@ latex_documents = [
u'OpenStack Foundation', 'manual'), 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 -------------------------------------------------------- # -- Custom extensions --------------------------------------------------------

15
doc/source/contributor/placement.rst
View File

@ -40,10 +40,11 @@ increasing the number of WSGI application instances and scaling the RDBMS using
traditional database scaling techniques. traditional database scaling techniques.
For sake of consistency and because there was initially intent to make the For sake of consistency and because there was initially intent to make the
entities in the placement service available over RPC, `versioned objects`_ are entities in the placement service available over RPC,
used to provide the interface between the HTTP application layer and the :oslo.versionedobjects-doc:`versioned objects <>` are used to provide the
SQLAlchemy-driven persistence layer. Even without RPC, these objects provide interface between the HTTP application layer and the SQLAlchemy-driven
useful structuring and separation of the code. 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 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 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. microversion and give a very brief summary of the added feature.
* Update ``nova/api/openstack/placement/rest_api_version_history.rst`` * Update ``nova/api/openstack/placement/rest_api_version_history.rst``
to add a more detailed section describing the new microversion. to add a more detailed section describing the new microversion.
* Add a `release note`_ with a ``features`` section announcing the new or * Add a :reno-doc:`release note <>` with a ``features`` section announcing the
changed feature and the microversion. new or changed feature and the microversion.
* If the ``version_handler`` decorator (see below) has been used, * If the ``version_handler`` decorator (see below) has been used,
increment ``TOTAL_VERSIONED_METHODS`` in increment ``TOTAL_VERSIONED_METHODS`` in
``nova/tests/unit/api/openstack/placement/test_microversion.py``. ``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. for an eventual extraction and avoid creating unnecessary interdependencies.
.. _WSGI: https://www.python.org/dev/peps/pep-3333/ .. _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 .. _wsgify: http://docs.webob.org/en/latest/api/dec.html
.. _WebOb: http://docs.webob.org/en/latest/ .. _WebOb: http://docs.webob.org/en/latest/
.. _Request: http://docs.webob.org/en/latest/reference.html#request .. _Request: http://docs.webob.org/en/latest/reference.html#request
.. _Response: http://docs.webob.org/en/latest/#response .. _Response: http://docs.webob.org/en/latest/#response
.. _microversions: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html .. _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/ .. _gabbi: https://gabbi.readthedocs.io/
.. _telemetry: http://specs.openstack.org/openstack/telemetry-specs/specs/kilo/declarative-http-tests.html .. _telemetry: http://specs.openstack.org/openstack/telemetry-specs/specs/kilo/declarative-http-tests.html
.. _wsgi-intercept: http://wsgi-intercept.readthedocs.io/ .. _wsgi-intercept: http://wsgi-intercept.readthedocs.io/

43
doc/source/index.rst
View File

@ -30,13 +30,12 @@ servers to provide that service.
It requires the following additional OpenStack services for basic function: It requires the following additional OpenStack services for basic function:
* `Keystone <https://docs.openstack.org/keystone/latest/>`__: This provides * :keystone-doc:`Keystone <>`: This provides identity and authentication for
identity and authentication for all OpenStack services. all OpenStack services.
* `Glance <https://docs.openstack.org/glance/latest/>`__: This provides the * :glance-doc:`Glance <>`: This provides the compute image repository. All
compute image repository. All compute instances launch from glance images. compute instances launch from glance images.
* `Neutron <https://docs.openstack.org/neutron/latest/>`__: This is * :neutron-doc:`Neutron <>`: This is responsible for provisioning the virtual
responsible for provisioning the virtual or physical networks that compute or physical networks that compute instances connect to on boot.
instances connect to on boot.
It can also integrate with other services to include: persistent block It can also integrate with other services to include: persistent block
storage, encrypted disks, and baremetal compute instances. storage, encrypted disks, and baremetal compute instances.
@ -50,19 +49,15 @@ either tools or the API directly.
Tools for using Nova Tools for using Nova
-------------------- --------------------
* `Horizon * :horizon-doc:`Horizon <user/launch-instances.html>`: The official web UI for
<https://docs.openstack.org/horizon/latest/user/launch-instances.html>`_: The the OpenStack Project.
official web ui for the OpenStack Project. * :python-openstackclient-doc:`OpenStack Client <>`: The official CLI for
* `OpenStack Client OpenStack Projects. You should use this as your CLI for most things, it
<https://docs.openstack.org/python-openstackclient/latest/>`_: The official includes not just nova commands but also commands for most of the projects in
CLI for OpenStack Projects. You should use this as your CLI for most things, OpenStack.
it includes not just nova commands but also commands for most of the projects * :python-novaclient-doc:`Nova Client <user/shell.html>`: For some very
in OpenStack. advanced features (or administrative commands) of nova you may need to use
* `Nova Client nova client. It is still supported, but the ``openstack`` cli is recommended.
<https://docs.openstack.org/python-novaclient/latest/user/shell.html>`_: 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 Writing to the API
------------------ ------------------
@ -117,11 +112,9 @@ Installation
.. TODO(sdague): links to all the rest of the install guide pieces. .. TODO(sdague): links to all the rest of the install guide pieces.
The detailed install guide for nova. A functioning nova will also require The detailed install guide for nova. A functioning nova will also require
having installed `keystone having installed :keystone-doc:`keystone <install/>`, :glance-doc:`glance
<https://docs.openstack.org/keystone/latest/install/>`__, `glance <install/>`, and :neutron-doc:`neutron <install/>`. Ensure that you follow
<https://docs.openstack.org/glance/latest/install/>`__, and `neutron their install guides first.
<https://docs.openstack.org/neutron/latest/install/>`__. Please ensure that you
follow their install guides first.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

8
doc/source/install/controller-install-obs.rst
View File

@ -379,10 +379,10 @@ Install and configure components
Compute firewall driver by using the Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver. ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
`Networking service install guide`__ for more details. the :neutron-doc:`Networking service install guide
<install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service>`
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service for more details.
* In the ``[vnc]`` section, configure the VNC proxy to use the management * In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node: interface IP address of the controller node:

7
doc/source/install/controller-install-rdo.rst
View File

@ -369,10 +369,9 @@ Install and configure components
Compute firewall driver by using the Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver. ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
`Networking service install guide`__ for more details. the :neutron-doc:`Networking service install guide
<install/compute-install-rdo.html>` for more details.
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-rdo.html#configure-the-compute-service-to-use-the-networking-service
* In the ``[vnc]`` section, configure the VNC proxy to use the management * In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node: interface IP address of the controller node:

8
doc/source/install/controller-install-ubuntu.rst
View File

@ -359,10 +359,10 @@ Install and configure components
Compute firewall driver by using the Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver. ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
`Networking service install guide`__ for more details. the :neutron-doc:`Networking service install guide
<install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service>`
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service for more information.
* In the ``[vnc]`` section, configure the VNC proxy to use the management * In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node: interface IP address of the controller node:

6
placement-api-ref/source/conf.py
View File

@ -88,3 +88,9 @@ latex_documents = [
('index', 'Placement.tex', u'OpenStack Placement API Documentation', ('index', 'Placement.tex', u'OpenStack Placement API Documentation',
u'OpenStack Foundation', 'manual'), u'OpenStack Foundation', 'manual'),
] ]
# -- Options for openstackdocstheme -------------------------------------------
openstack_projects = [
'nova',
]

4
placement-api-ref/source/index.rst
View File

@ -5,8 +5,8 @@
=============== ===============
This is a reference for the OpenStack Placement API. To learn more about This is a reference for the OpenStack Placement API. To learn more about
OpenStack Placement API concepts, please refer to the OpenStack Placement API concepts, please refer to the :nova-doc:`Placement
`Placement Introduction <https://docs.openstack.org/nova/latest/user/placement.html>`_. Introduction <user/placement.html>`.
The Placement API uses JSON for data exchange. As such, the ``Content-Type`` 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 header for APIs sending data payloads in the request body (i.e. ``PUT`` and