From 79165aa469cf8252c85903c230f6714d3dd2c607 Mon Sep 17 00:00:00 2001
From: Colleen Murphy <colleen.murphy@suse.de>
Date: Wed, 12 Dec 2018 08:50:22 +0100
Subject: [PATCH] Split trusts docs between admin and user guide

Trusts are user-facing, so explaining how they work should be in the
user guide. Cleaning up expired trusts is still an administrative task,
so leave that in the admin guide.

Change-Id: I9a77efd3c93c9b5b504c8143a51fb08b50139119
---
 doc/source/admin/index.rst                    |  2 +-
 doc/source/admin/manage-trusts.rst            | 29 ++++++++++++
 doc/source/user/index.rst                     |  1 +
 .../{admin/use-trusts.rst => user/trusts.rst} | 44 ++++++++++---------
 4 files changed, 54 insertions(+), 22 deletions(-)
 create mode 100644 doc/source/admin/manage-trusts.rst
 rename doc/source/{admin/use-trusts.rst => user/trusts.rst} (68%)

diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 213e98eb9d..309d5ce536 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -25,7 +25,7 @@ command-line client.
    upgrading.rst
    tokens.rst
    fernet-token-faq.rst
-   use-trusts.rst
+   manage-trusts.rst
    caching-layer.rst
    security-compliance.rst
    resource-options.rst
diff --git a/doc/source/admin/manage-trusts.rst b/doc/source/admin/manage-trusts.rst
new file mode 100644
index 0000000000..03337e3ea7
--- /dev/null
+++ b/doc/source/admin/manage-trusts.rst
@@ -0,0 +1,29 @@
+===============
+Managing trusts
+===============
+
+A trust is an OpenStack Identity extension that enables delegation and,
+optionally, impersonation through ``keystone``. See the `user guide on using
+trusts`_.
+
+.. _user guide on using trusts: ../user/trusts.html
+
+Removing Expired Trusts
+===========================================================
+
+In the SQL trust stores expired and soft deleted trusts, that are not
+automatically removed. These trusts can be removed with::
+
+    $ keystone-manage trust_flush [options]
+
+ OPTIONS (optional):
+
+        --project-id <string>:
+                    To purge trusts of given project-id.
+        --trustor-user-id <string>:
+                    To purge trusts of given trustor-id.
+        --trustee-user-id <string>:
+                    To purge trusts of given trustee-id.
+        --date <string>:
+                    To purge trusts older than date. If no date is supplied
+                    keystone-manage will use the system clock time at runtime.
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index 4581152d32..cc9a178206 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -27,5 +27,6 @@ An end user can find the specific API documentation here, `OpenStack's Identity
 
     supported_clients.rst
     application_credentials.rst
+    trusts.rst
     json_home.rst
     ../api_curl_examples.rst
diff --git a/doc/source/admin/use-trusts.rst b/doc/source/user/trusts.rst
similarity index 68%
rename from doc/source/admin/use-trusts.rst
rename to doc/source/user/trusts.rst
index b84620e13e..69fefd3386 100644
--- a/doc/source/admin/use-trusts.rst
+++ b/doc/source/user/trusts.rst
@@ -1,6 +1,22 @@
-==========
-Use trusts
-==========
+..
+      Copyright 2018 SUSE Linux GmbH
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+======
+Trusts
+======
 
 OpenStack Identity manages authentication and authorization. A trust is
 an OpenStack Identity extension that enables delegation and, optionally,
@@ -55,23 +71,9 @@ The delegation parameters are:
 **Duration**
   (Optional) Comprised of the start time and end time for the trust.
 
+.. note::
 
-Removing Expired Trusts
-===========================================================
+   See the administrator guide on `removing expired trusts`_ for recommended
+   maintenance procedures.
 
-In the SQL trust stores expired and soft deleted trusts, that are not
-automatically removed. These trusts can be removed with::
-
-    $ keystone-manage trust_flush [options]
-
- OPTIONS (optional):
-
-        --project-id <string>:
-                    To purge trusts of given project-id.
-        --trustor-user-id <string>:
-                    To purge trusts of given trustor-id.
-        --trustee-user-id <string>:
-                    To purge trusts of given trustee-id.
-        --date <string>:
-                    To purge trusts older than date. If no date is supplied
-                    keystone-manage will use the system clock time at runtime.
+.. _`removing expired trusts`: ../admin/manage-trusts.html