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

@@ -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

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.

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

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