From aa75bfa8f06dd2c71e0fbda75f7f1a3415824992 Mon Sep 17 00:00:00 2001 From: Riccardo Pittau Date: Fri, 4 Oct 2019 11:54:47 +0200 Subject: [PATCH] docs: use openstackdocstheme extlink extension The extlink extension [1] ensures the urls have version-specific references to other projects. [1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper Change-Id: I59ae4e28a02ee2683d35cf46857386e3f458ec2c Story: 2006621 Task: 36917 --- doc/source/admin/dnsmasq-pxe-filter.rst | 9 ++++--- doc/source/conf.py | 10 ++++++++ doc/source/install/index.rst | 31 ++++++++++++------------- doc/source/user/http-api.rst | 15 ++++++------ doc/source/user/troubleshooting.rst | 4 ++-- doc/source/user/usage.rst | 12 ++++------ doc/source/user/workflow.rst | 10 ++++---- 7 files changed, 48 insertions(+), 43 deletions(-) diff --git a/doc/source/admin/dnsmasq-pxe-filter.rst b/doc/source/admin/dnsmasq-pxe-filter.rst index 4e0e77495..10ce14495 100644 --- a/doc/source/admin/dnsmasq-pxe-filter.rst +++ b/doc/source/admin/dnsmasq-pxe-filter.rst @@ -82,9 +82,10 @@ commands to, for instance, directly control the **dnsmasq** service:: .. note:: - These commands are executed through the rootwrap_ facility, so overriding - may require a filter file to be created in the ``rootwrap.d`` directory. A - sample configuration to use with the **systemctl** facility might be: + These commands are executed through the :oslo.rootwrap-doc:`rootwrap <>` + facility, so overriding may require a filter file to be created in the + ``rootwrap.d`` directory. A sample configuration to use with the + **systemctl** facility might be: .. code-block:: console @@ -95,8 +96,6 @@ commands to, for instance, directly control the **dnsmasq** service:: systemctl: CommandFilter, systemctl, root, stop, dnsmasq EOF - .. _rootwrap: https://docs.openstack.org/oslo.rootwrap/latest/ - Caveats ------- diff --git a/doc/source/conf.py b/doc/source/conf.py index e0917fbee..be72b5be1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,6 +21,16 @@ except ImportError: repository_name = 'openstack/ironic-inspector' use_storyboard = True +openstack_projects = [ + 'bifrost', + 'devstack', + 'ironic', + 'ironic-python-agent', + 'oslo.rootwrap', + 'python-ironicclient', + 'python-ironic-inspector-client', + 'tooz', +] wsme_protocols = ['restjson'] diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index f893114d2..a60c84767 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -6,19 +6,17 @@ environment):: pip install ironic-inspector -Also there is a `DevStack `_ -plugin for **ironic-inspector** - see :ref:`contributing_link` for the -current status. +Also there is a :devstack-doc:`DevStack <>` plugin for **ironic-inspector** - +see :ref:`contributing_link` for the current status. Finally, some distributions (e.g. Fedora) provide **ironic-inspector** packaged, some of them - under its old name *ironic-discoverd*. There are several projects you can use to set up **ironic-inspector** in -production. `puppet-ironic -`_ provides Puppet -manifests, while `bifrost `_ -provides an Ansible-based standalone installer. Refer to Configuration_ -if you plan on installing **ironic-inspector** manually. +production. `puppet-ironic `_ +provides Puppet manifests, while :bifrost-doc:`bifrost <>` provides an +Ansible-based standalone installer. Refer to Configuration_ if you plan on +installing **ironic-inspector** manually. .. _PyPI: https://pypi.org/project/ironic-inspector @@ -90,7 +88,7 @@ non-standalone mode: is configured to use ``etcd3+http://``, ``pymemcache`` is required to use ``memcached://``. Some distributions may provide packages like ``python3-etcd3gw`` or ``python3-memcache``. Supported drivers are listed at - `Tooz drivers `_. + :tooz-doc:`Tooz drivers `. * For ironic-inspector running in non-standalone mode, PXE configuration is only required on the node where ironic-inspector conductor service is @@ -228,9 +226,9 @@ Replace ``stack`` with whatever user you'll be using to run Configuring IPA ~~~~~~~~~~~~~~~ -ironic-python-agent_ is a ramdisk developed for **ironic** and support -for **ironic-inspector** was added during the Liberty cycle. This is the -default ramdisk starting with the Mitaka release. +:ironic-python-agent-doc:`ironic-python-agent <>` is a ramdisk developed for +**ironic** and support for **ironic-inspector** was added during the Liberty +cycle. This is the default ramdisk starting with the Mitaka release. .. note:: You need at least 1.5 GiB of RAM on the machines to use IPA built with @@ -254,11 +252,10 @@ To build an **ironic-python-agent** ramdisk, do the following: Alternatively, you can download a `prebuilt TinyIPA image `_ or use -the `other builders -`_. +the :ironic-python-agent-doc:`other builders +`. .. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/ -.. _ironic-python-agent: https://docs.openstack.org/ironic-python-agent/latest/ Configuring PXE ~~~~~~~~~~~~~~~ @@ -472,7 +469,9 @@ service. Below is a sample configuration for Apache with module mod_wsgi:: -You can refer to `ironic installation document `_ +You can refer to +:ironic-doc:`ironic installation document +` for more guides. ironic-inspector conductor can be started with:: diff --git a/doc/source/user/http-api.rst b/doc/source/user/http-api.rst index debb9b13f..96ac6e3aa 100644 --- a/doc/source/user/http-api.rst +++ b/doc/source/user/http-api.rst @@ -227,8 +227,10 @@ Ramdisk Callback discovered data. Should not be used for anything other than implementing the ramdisk. Request body: JSON dictionary with at least these keys: -* ``inventory`` full `hardware inventory`_ from the ironic-python-agent with at - least the following keys: +* ``inventory`` full + :ironic-python-agent-doc:`hardware inventory + ` + from the ironic-python-agent with at least the following keys: * ``memory`` memory information containing at least key ``physical_mb`` - physical memory size as reported by dmidecode, @@ -258,8 +260,9 @@ the ramdisk. Request body: JSON dictionary with at least these keys: .. note:: **ironic-inspector** default plugin ``root_disk_selection`` may change ``root_disk`` based on root device hints if node specify hints via - properties ``root_device`` key. See `Specifying the disk for deployment - root device hints`_ for more details. + properties ``root_device`` key. See + :ironic-doc:`Specifying the disk for deployment root device hints ` + for more details. * ``boot_interface`` MAC address of the NIC that the machine PXE booted from either in standard format ``11:22:33:44:55:66`` or in *PXELinux* ``BOOTIF`` @@ -291,10 +294,6 @@ Response: Response body: JSON dictionary with ``uuid`` key. -.. _hardware inventory: https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory -.. _Specifying the disk for deployment root device hints: - https://docs.openstack.org/ironic/latest/install/advanced.html#specifying-the-disk-for-deployment-root-device-hints - Error Response ~~~~~~~~~~~~~~ diff --git a/doc/source/user/troubleshooting.rst b/doc/source/user/troubleshooting.rst index 5160a1580..2f55b18f9 100644 --- a/doc/source/user/troubleshooting.rst +++ b/doc/source/user/troubleshooting.rst @@ -22,8 +22,8 @@ There may be 3 reasons why introspection can time out after some time #. Fatal failure in processing chain before node was found in the local cache. See `Troubleshooting data processing`_ for the hints. -#. Failure to load the ramdisk on the target node. See `Troubleshooting - PXE boot`_ for the hints. +#. Failure to load the ramdisk on the target node. See + `Troubleshooting PXE boot`_ for the hints. #. Failure during ramdisk run. See `Troubleshooting ramdisk run`_ for the hints. diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index cbf3747df..8b48dd7a7 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -4,19 +4,17 @@ Usage .. _usage_guide: Refer to :ref:`api ` for information on the HTTP API. -Refer to the `client documentation`_ for information on how to use CLI and -Python library. - -.. _client documentation: https://docs.openstack.org/python-ironic-inspector-client/latest/ +Refer to the :python-ironic-inspector-client-doc:`client documentation <>` +for information on how to use CLI and Python library. Using from Ironic API ~~~~~~~~~~~~~~~~~~~~~ Ironic Kilo introduced support for hardware introspection under name of "inspection". **ironic-inspector** introspection is supported for some generic -drivers, please refer to `Ironic inspection documentation`_ for details. - -.. _Ironic inspection documentation: https://docs.openstack.org/ironic/latest/admin/inspection.html +drivers, please refer to +:ironic-doc:`Ironic inspection documentation ` +for details. Node States ~~~~~~~~~~~ diff --git a/doc/source/user/workflow.rst b/doc/source/user/workflow.rst index 542b3a066..8acd4008e 100644 --- a/doc/source/user/workflow.rst +++ b/doc/source/user/workflow.rst @@ -6,7 +6,8 @@ Workflow Usual hardware introspection flow is as follows: -* Operator enrolls nodes into Ironic_ e.g. via `openstack baremetal CLI`_ +* Operator enrolls nodes into Ironic_ e.g. via + :python-ironicclient-doc:`openstack baremetal CLI ` command. Power management credentials should be provided to Ironic at this step. @@ -50,15 +51,15 @@ Usual hardware introspection flow is as follows: Ironic inspection feature by default requires different settings: ``add_ports=all``, ``keep_ports=present``, which means that ports will be created for all detected NIC's, and all other ports will be deleted. - Refer to the `Ironic inspection documentation`_ for details. + Refer to the + :ironic-doc:`Ironic inspection documentation ` + for details. Ironic inspector can also be configured to not create any ports. This is done by setting ``add_ports=disabled``. If setting ``add_ports`` to disabled the ``keep_ports`` option should be also set to ``all``. This will ensure no manually added ports will be deleted. -.. _Ironic inspection documentation: https://docs.openstack.org/ironic/latest/admin/inspection.html - * Separate API (see :ref:`usage ` and :ref:`api `) can be used to query introspection results for a given node. @@ -83,4 +84,3 @@ The diagram also shows events that trigger state transitions. :alt: ironic-inspector state machine diagram .. _Ironic: https://wiki.openstack.org/wiki/Ironic -.. _openstack baremetal CLI: https://docs.openstack.org/python-ironicclient/latest/cli/osc_plugin_cli.html