From 39e7c2d3200b2e2895650ff28e73ee49eb4b369f Mon Sep 17 00:00:00 2001 From: Luigi Toscano Date: Fri, 8 Jun 2018 16:08:50 +0200 Subject: [PATCH] doc: external link helper for other projects' doc The external link helper makes sure that the generated link respects the current branch (latest for master, when built on stable/. Do not use it for sahara-tests (which is branchless). Change-Id: Ie37fe37858a41f54558642ea93a75365668ef573 --- .../admin/advanced-configuration-guide.rst | 28 +++++++++---------- doc/source/conf.py | 15 ++++++++++ .../contributor/development-guidelines.rst | 6 ++-- doc/source/install/installation-guide.rst | 6 ++-- doc/source/reference/restapi.rst | 4 +-- doc/source/user/features.rst | 5 ++-- doc/source/user/sahara-on-ironic.rst | 6 ++-- 7 files changed, 41 insertions(+), 29 deletions(-) diff --git a/doc/source/admin/advanced-configuration-guide.rst b/doc/source/admin/advanced-configuration-guide.rst index 00fa07bab2..22c9f6107d 100644 --- a/doc/source/admin/advanced-configuration-guide.rst +++ b/doc/source/admin/advanced-configuration-guide.rst @@ -58,10 +58,12 @@ displayed as hostnames instead of just ip addresses. You should configure DNS server with Designate. Designate service should be properly installed and registered in Keystone catalog. The detailed -instructions about Designate configuration can be found here: `Designate manual -installation`_ and here: `Configuring OpenStack Networking with Designate`_. -Also if you use devstack you can just enable Designate plugin: -`Designate devstack`_. +instructions about Designate configuration can be found here: +:designate-doc:`Designate manual installation ` +and here: :neutron-doc:`Configuring OpenStack Networking with Designate +`. +Also if you use devstack you can just enable the +:designate-doc:`Designate devstack plugin `. When Designate is configured you should create domain(s) for hostname resolution. This can be done by using the Designate dashboard or by CLI. Also @@ -94,10 +96,6 @@ change your ``/etc/resolv.conf`` file by adding appropriate ip addresses of DNS servers (e.g. 1.1.1.1 and 2.2.2.2). Also the VMs with DNS servers should be available from your local machine. -.. _Designate manual installation: https://docs.openstack.org/designate/latest/install/index.html -.. _Configuring OpenStack Networking with Designate: https://docs.openstack.org/neutron/latest/admin/config-dns-int.html#configuring-openstack-networking-for-integration-with-an-external-dns-service -.. _Designate devstack: https://docs.openstack.org/designate/latest/contributor/devstack.html - .. _data_locality_configuration: Data-locality configuration @@ -265,7 +263,8 @@ Distributed periodic tasks are based on Hash Ring implementation and the Tooz library that provides group membership support for a set of backends. In order to use periodic tasks distribution, the following steps are required: -* One of the `supported backends `_ should be configured and started. +* One of the :tooz-doc:`supported backends ` + should be configured and started. * Backend URL should be set in the sahara configuration file with the ``periodic_coordinator_backend_url`` parameter. For example, if the ZooKeeper backend is being used: @@ -324,7 +323,7 @@ within the stack. With a Key Manager service deployed on the stack, sahara must be configured to enable the external storage of secrets. Sahara uses the -`castellan `_ library +:castellan-doc:`castellan <>` library to interface with the OpenStack Key Manager service. This library provides configurable access to a key manager. To configure sahara to use barbican as the key manager, edit the sahara configuration file as follows: @@ -485,9 +484,8 @@ users created by sahara. This domain must have an identity backend driver that allows for sahara to create new users. The default SQL engine is sufficient but if your keystone identity is backed by LDAP or similar then domain specific configurations should be used to ensure sahara's -access. Please see the `Keystone documentation`_ for more information. - -.. _Keystone documentation: https://docs.openstack.org/keystone/latest/configuration.html#domain-specific-drivers +access. Please see the :keystone-doc:`Keystone documentation +` for more information. With the domain created, sahara's configuration file should be updated to include the new domain name and any potential roles that will be needed. For @@ -617,7 +615,8 @@ CORS (Cross Origin Resource Sharing) Configuration Sahara provides direct API access to user-agents (browsers) via the HTTP CORS protocol. Detailed documentation, as well as troubleshooting examples, -may be found in the OpenStack `Administrator Guide`_. +may be found in the :oslo.middleware-doc:`documentation of the oslo.db +cross-project features `. To get started quickly, use the example configuration block below, replacing the :code:`allowed origin` field with the host(s) from which your API expects @@ -639,7 +638,6 @@ access. For more information on Cross Origin Resource Sharing, please review the `W3C CORS specification`_. -.. _Administrator Guide: https://docs.openstack.org/oslo.middleware/latest/admin/cross-project-cors.html .. _W3C CORS specification: http://www.w3.org/TR/cors/ Cleanup time for incomplete clusters diff --git a/doc/source/conf.py b/doc/source/conf.py index a1238a72dc..3e0920d2af 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -48,6 +48,21 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M' config_generator_config_file = 'config-generator.conf' config_sample_basename = 'sahara' +openstack_projects = [ + 'barbican', + 'castellan', + 'designate', + 'devstack', + 'ironic', + 'keystone', + 'keystoneauth', + 'kolla-ansible', + 'neutron', + 'nova', + 'oslo.middleware', + 'tooz' +] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/source/contributor/development-guidelines.rst b/doc/source/contributor/development-guidelines.rst index ec68364ae5..66471efdb5 100644 --- a/doc/source/contributor/development-guidelines.rst +++ b/doc/source/contributor/development-guidelines.rst @@ -178,7 +178,7 @@ keystone ``Session`` and auth plugin objects (for example, ``Token`` and ``Password``). Sahara is migrating all clients to use this authentication methodology, where available. For more information on using sessions with keystone, please see -https://docs.openstack.org/keystoneauth/latest/using-sessions.html +:keystoneauth-doc:`the keystoneauth documentation ` Storing sensitive information ----------------------------- @@ -188,8 +188,8 @@ information (for example, login credentials) in the records for a cluster, job, or some other record. Storing secret information this way is **not** safe. To mitigate the risk of storing this information, sahara provides access to the OpenStack Key Manager service (implemented by the -`barbican project `_) through -the `castellan library `_. +:barbican-doc:`barbican project <>`) through +the :castellan-doc:`castellan library <>`. To utilize the external key manager, the functions in ``sahara.service.castellan.utils`` are provided as wrappers around the diff --git a/doc/source/install/installation-guide.rst b/doc/source/install/installation-guide.rst index 84a4f0bf0d..9b639bc835 100644 --- a/doc/source/install/installation-guide.rst +++ b/doc/source/install/installation-guide.rst @@ -6,7 +6,7 @@ consistent state. We suggest the following options: * Install via `Fuel `_ -* Install via `Kolla `_ +* Install via :kolla-ansible-doc:`Kolla <>` * Install via `RDO `_ @@ -26,8 +26,8 @@ To install with Fuel To install with Kolla --------------------- -1. Start by following the `Kolla Quickstart - `_ +1. Start by following the :kolla-ansible-doc:`Kolla Quickstart + ` to install and setup OpenStack. 2. Enable the sahara service during installation. diff --git a/doc/source/reference/restapi.rst b/doc/source/reference/restapi.rst index 2d6999361a..7f23b225d9 100644 --- a/doc/source/reference/restapi.rst +++ b/doc/source/reference/restapi.rst @@ -14,8 +14,8 @@ authentication service. When the Identity service is enabled, users who submit requests to the sahara service must provide an authentication token in the ``X-Auth-Token`` request header. A user can obtain the token by authenticating to the Identity service endpoint. For more information about -the Identity service, please see the `keystone project developer documentation -`_ +the Identity service, please see the :keystone-doc:`keystone project developer +documentation <>`. With each request, a user must specify the keystone project in the url path, for example: '/v1.1/{project_id}/clusters'. Sahara diff --git a/doc/source/user/features.rst b/doc/source/user/features.rst index 64e500d869..2e2b9c0f99 100644 --- a/doc/source/user/features.rst +++ b/doc/source/user/features.rst @@ -23,14 +23,13 @@ processes to increase HDFS replica reliability. Starting with the Juno release, sahara can create server groups with the ``anti-affinity`` policy to enable this feature. Sahara creates one server group per cluster and assigns all instances with affected processes to -this server group. Refer to the `Nova Anti-Affinity documentation`_ +this server group. Refer to the :nova-doc:`Nova Anti-Affinity documentation +` on how server group affinity filters work. This feature is supported by all plugins out of the box, and can be enabled during the cluster template creation. -.. _Nova Anti-Affinity documentation: https://docs.openstack.org/nova/latest/admin/configuration/schedulers.html#servergroupantiaffinityfilter - Block Storage support --------------------- diff --git a/doc/source/user/sahara-on-ironic.rst b/doc/source/user/sahara-on-ironic.rst index 4630d3ee41..b9fc926526 100644 --- a/doc/source/user/sahara-on-ironic.rst +++ b/doc/source/user/sahara-on-ironic.rst @@ -9,10 +9,10 @@ from the bare metal performance with self-service resource provisioning. 1. Create a new OpenStack environment using Devstack as described - in the `Devstack Guide `_ + in the :devstack-doc:`Devstack Guide <>` -2. Install Ironic as described in the `Ironic Installation Guide - `_ +2. Install Ironic as described in the :ironic-doc:`Ironic Installation Guide + ` 3. Install Sahara as described in the `Sahara Installation Guide <../install/installation-guide.html>`_