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
This commit is contained in:
Stephen Finucane
parent
07d982aa1c
commit
2925105d0f
@ -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
|
||||
|
||||
@ -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 --------------------------------------------------------
|
||||
|
||||
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -30,13 +30,12 @@ servers to provide that service.
|
||||
|
||||
It requires the following additional OpenStack services for basic function:
|
||||
|
||||
* `Keystone <https://docs.openstack.org/keystone/latest/>`__: This provides
|
||||
identity and authentication for all OpenStack services.
|
||||
* `Glance <https://docs.openstack.org/glance/latest/>`__: This provides the
|
||||
compute image repository. All compute instances launch from glance images.
|
||||
* `Neutron <https://docs.openstack.org/neutron/latest/>`__: 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
|
||||
<https://docs.openstack.org/horizon/latest/user/launch-instances.html>`_: The
|
||||
official web ui for the OpenStack Project.
|
||||
* `OpenStack Client
|
||||
<https://docs.openstack.org/python-openstackclient/latest/>`_: 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
|
||||
<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.
|
||||
* :horizon-doc:`Horizon <user/launch-instances.html>`: 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 <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
|
||||
------------------
|
||||
@ -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
|
||||
<https://docs.openstack.org/keystone/latest/install/>`__, `glance
|
||||
<https://docs.openstack.org/glance/latest/install/>`__, and `neutron
|
||||
<https://docs.openstack.org/neutron/latest/install/>`__. Please ensure that you
|
||||
follow their install guides first.
|
||||
having installed :keystone-doc:`keystone <install/>`, :glance-doc:`glance
|
||||
<install/>`, and :neutron-doc:`neutron <install/>`. Ensure that you follow
|
||||
their install guides first.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
@ -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
|
||||
<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
|
||||
interface IP address of the controller node:
|
||||
|
||||
@ -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
|
||||
<install/compute-install-rdo.html>` for more details.
|
||||
|
||||
* In the ``[vnc]`` section, configure the VNC proxy to use the management
|
||||
interface IP address of the controller node:
|
||||
|
||||
@ -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
|
||||
<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
|
||||
interface IP address of the controller node:
|
||||
|
||||
@ -88,3 +88,9 @@ latex_documents = [
|
||||
('index', 'Placement.tex', u'OpenStack Placement API Documentation',
|
||||
u'OpenStack Foundation', 'manual'),
|
||||
]
|
||||
|
||||
# -- Options for openstackdocstheme -------------------------------------------
|
||||
|
||||
openstack_projects = [
|
||||
'nova',
|
||||
]
|
||||
|
||||
@ -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 <https://docs.openstack.org/nova/latest/user/placement.html>`_.
|
||||
OpenStack Placement API concepts, please refer to the :nova-doc:`Placement
|
||||
Introduction <user/placement.html>`.
|
||||
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user