rearrange existing documentation to follow the new layout standard

This change moves existing files, updates a few of the cross-references
and paths, and fixes some formatting. It is not meant to be the final
word on how the main page looks or how the other files are organized,
but it gets everything roughly into shape. If the glance team wants to
make changes, please do those as follow-up patches

This change depends on the spec and on a feature of pbr that allows us
to move where the auto-generated class reference documentation ends up
in the tree.

Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Depends-On: I2bd5652bb59cbd9c939931ba2e7db1b37d2b30bb
Change-Id: I9dde267793a5913acb5b1ec028cfb66bc5189783
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

.gitignore

@@ -27,6 +27,7 @@ subunit.log
 # Files created by doc build
 doc/source/api
 doc/source/_static/*.sample
+doc/source/contributor/api
 
 # Files created by releasenotes build
 releasenotes/build

doc/source/admin/index.rst

@@ -0,0 +1,20 @@
+======================
+ Administration guide
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   tasks
+   authentication
+   policies
+   flows
+   property-protections
+   requirements
+   apache-httpd
+   controllingservers
+   db
+   db-sqlalchemy-migrate
+   rollingupgrades
+   cache
+   notifications

doc/source/configuration/configuring.rst

@@ -1326,6 +1326,7 @@ with the glance-api service when clients are using the v1 REST API. See
 
 ``sql_connection=CONNECTION_STRING`` (``--sql-connection`` when specified
 on command line)
+
   Optional. Default: ``None``
 
   Can be specified in configuration files. Can also be specified on the
@@ -1337,6 +1338,7 @@ on command line)
   online. You must urlencode any special characters in CONNECTION_STRING.
 
 ``sql_timeout=SECONDS``
+
   Optional. Default: ``3600``
 
   Can only be specified in configuration files.
@@ -1345,9 +1347,11 @@ on command line)
   datastore if no activity has been made on the connection.
 
 ``enable_v1_registry=<True|False>``
+
   Optional. Default: ``True``
 
 ``enable_v2_registry=<True|False>``
+
   Optional. Default: ``True``
 
   Defines which version(s) of the Registry API will be enabled.
@@ -1366,6 +1370,7 @@ queue. The configuration options are specified in the ``glance-api.conf``
 configuration file.
 
 ``[oslo_messaging_notifications]/driver``
+
   Optional. Default: ``noop``
 
   Sets the notification driver used by oslo.messaging. Options include
@@ -1379,6 +1384,7 @@ configuration file.
   `oslo.messaging <http://docs.openstack.org/developer/oslo.messaging/>`_.
 
 ``[DEFAULT]/disabled_notifications``
+
   Optional. Default: ``[]``
 
   List of disabled notifications. A notification can be given either as a
@@ -1399,12 +1405,14 @@ configuration file in the section ``[DEFAULT]``. **If an incorrect value is
 specified, glance API service will not start.**
 
 ``property_protection_file=PATH``
+
   Optional. Default: not enabled.
 
   If property_protection_file is set, the file may use either roles or policies
   to specify property protections.
 
 ``property_protection_rule_format=<roles|policies>``
+
   Optional. Default: ``roles``.
 
 Configuring Glance APIs
@@ -1415,9 +1423,11 @@ the OpenStack Images API. Disable any version of
 the Images API using the following options:
 
 ``enable_v1_api=<True|False>``
+
   Optional. Default: ``True``
 
 ``enable_v2_api=<True|False>``
+
   Optional. Default: ``True``
 
   **IMPORTANT NOTE**: To use v2 registry in v2 API, you must set
@@ -1433,6 +1443,7 @@ would be visible to the user after transitioning to either the ``success`` or
 the ``failure`` state.
 
 ``task_time_to_live=<Time_in_hours>``
+
   Optional. Default: ``48``
 
   The config value ``task_executor`` is used to determine which executor
@@ -1440,6 +1451,7 @@ the ``failure`` state.
   available implementation is: ``taskflow``.
 
 ``task_executor=<executor_type>``
+
   Optional. Default: ``taskflow``
 
   The ``taskflow`` engine has its own set of configuration options,
@@ -1469,6 +1481,7 @@ The config value ``enabled`` is used to determine whether fully enable
 profiling feature for glance-api and glance-registry service.
 
 ``enabled=<True|False>``
+
   Optional. Default: ``False``
 
   There is one more configuration option that needs to be defined to enable
@@ -1476,6 +1489,7 @@ profiling feature for glance-api and glance-registry service.
   encrypting context data for performance profiling.
 
 ``hmac_keys=<secret_key_string>``
+
   Optional. Default: ``SECRET_KEY``
 
   **IMPORTANT NOTE**: in order to make profiling work as designed operator needs
@@ -1495,6 +1509,7 @@ profiling feature for glance-api and glance-registry service.
   glance-registry services.
 
 ``trace_sqlalchemy=<True|False>``
+
   Optional. Default: ``False``
 
 Configuring Glance public endpoint
@@ -1510,6 +1525,7 @@ to individual hosts running the Glance API may not be allowed, hence the
 load balancer URL would be used for this value.
 
 ``public_endpoint=<None|URL>``
+
   Optional. Default: ``None``
 
 Configuring Glance digest algorithm
@@ -1526,12 +1542,14 @@ digest algorithm is configured, all digital signature operations will fail and
 return a ValueError exception with "No such digest method" error.
 
 ``digest_algorithm=<algorithm>``
+
   Optional. Default: ``sha256``
 
 Configuring http_keepalive option
 ---------------------------------
 
 ``http_keepalive=<True|False>``
+
   If False, server will return the header "Connection: close", If True, server
   will return "Connection: Keep-Alive" in its responses. In order to close the
   client socket connection explicitly after the response is sent and read
@@ -1579,4 +1597,5 @@ done by setting the ``disk_formats`` parameter which is found in the
 ``[image_formats]`` section of ``glance-api.conf``.
 
 ``disk_formats=<Comma separated list of disk formats>``
+
   Optional. Default: ``ami,ari,aki,vhd,vhdx,vmdk,raw,qcow2,vdi,iso,ploop``

doc/source/configuration/sample-configuration.rst

@@ -11,42 +11,42 @@ Sample configuration for Glance API
 -----------------------------------
 
 This sample configuration can also be viewed in `glance-api.conf.sample
-<_static/glance-api.conf.sample>`_.
+<../_static/glance-api.conf.sample>`_.
 
-.. literalinclude:: _static/glance-api.conf.sample
+.. literalinclude:: ../_static/glance-api.conf.sample
 
 
 Sample configuration for Glance Registry
 ----------------------------------------
 
 This sample configuration can also be viewed in `glance-registry.conf.sample
-<_static/glance-registry.conf.sample>`_.
+<../_static/glance-registry.conf.sample>`_.
 
-.. literalinclude:: _static/glance-registry.conf.sample
+.. literalinclude:: ../_static/glance-registry.conf.sample
 
 
 Sample configuration for Glance Scrubber
 ----------------------------------------
 
 This sample configuration can also be viewed in `glance-scrubber.conf.sample
-<_static/glance-scrubber.conf.sample>`_.
+<../_static/glance-scrubber.conf.sample>`_.
 
-.. literalinclude:: _static/glance-scrubber.conf.sample
+.. literalinclude:: ../_static/glance-scrubber.conf.sample
 
 
 Sample configuration for Glance Manage
 --------------------------------------
 
 This sample configuration can also be viewed in `glance-manage.conf.sample
-<_static/glance-manage.conf.sample>`_.
+<../_static/glance-manage.conf.sample>`_.
 
-.. literalinclude:: _static/glance-manage.conf.sample
+.. literalinclude:: ../_static/glance-manage.conf.sample
 
 
 Sample configuration for Glance Cache
 -------------------------------------
 
 This sample configuration can also be viewed in `glance-cache.conf.sample
-<_static/glance-cache.conf.sample>`_.
+<../_static/glance-cache.conf.sample>`_.
 
-.. literalinclude:: _static/glance-cache.conf.sample
+.. literalinclude:: ../_static/glance-cache.conf.sample

doc/source/contributor/architecture.rst

@@ -35,7 +35,7 @@ the components in the system and is sql-based by default. Other types
 of database backends are somewhat supported and used by operators
 but are not extensively tested upstream.
 
-.. figure:: ./images/architecture.png
+.. figure:: ../images/architecture.png
    :figwidth: 100%
    :align: center
    :alt: OpenStack Glance Architecture Diagram.

doc/source/contributor/database_architecture.rst

@@ -181,7 +181,7 @@ of an *Image* object.
 
 **Glance database schema**
 
-.. figure:: ./images/glance_db.png
+.. figure:: ../images/glance_db.png
    :figwidth: 100%
    :align: center
    :alt: The glance database schema is depicted by 5 tables.

doc/source/contributor/database_migrations.rst

@@ -340,8 +340,8 @@ References
 ==========
 .. [GSPEC1] `Database Strategy for Rolling Upgrades
             <https://specs.openstack.org/openstack/glance-specs/specs/ocata/implemented/glance/database-strategy-for-rolling-upgrades.html>`_
-.. [GSPEC2] `Glance Alembic Migrations
+.. [GSPEC2] `Glance Alembic Migrations Spec
             <https://specs.openstack.org/openstack/glance-specs/specs/ocata/implemented/glance/alembic-migrations.html>`_
-.. [GMIGS1] `Glance Alembic Migrations
+.. [GMIGS1] `Glance Alembic Migrations Implementation
             <http://git.openstack.org/cgit/openstack/glance/tree/glance/db/sqlalchemy/alembic_migrations/versions>`_
 .. [ALMBC] `Alembic Operations <http://alembic.zzzcomputing.com/en/latest/ops.html>`_

doc/source/contributor/domain_implementation.rst

@@ -34,7 +34,7 @@ The domain model contains the following layers:
 The schema below shows a stack that contains the Image domain layers and
 their locations:
 
-.. figure:: ./images/glance_layers.png
+.. figure:: ../images/glance_layers.png
    :figwidth: 100%
    :align: center
    :alt: From top to bottom, the stack consists of the Router and REST API,

doc/source/contributor/index.rst

@@ -19,6 +19,19 @@ This documentation is generated by the Sphinx toolkit and lives in the source
 tree. Additional documentation on Glance and other components of OpenStack can
 be found on the `OpenStack wiki <http://wiki.openstack.org>`_.
 
+Developer reference
+-------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   architecture
+   database_architecture
+   database_migrations
+   domain_model
+   domain_implementation
+   api/modules
+
 Policies
 --------
 .. toctree::

doc/source/index.rst

@@ -32,12 +32,14 @@ VM images made available through Glance can be stored in a variety of
 locations from simple filesystems to object-storage systems like the
 OpenStack Swift project.
 
-To learn how to contribute to Glance, see:
-
 .. toctree::
    :maxdepth: 2
 
-   contributing/index
+   user/index
+   admin/index
+   install/index
+   configuration/index
+   contributor/index
 
 Ocata
 ~~~~~
@@ -56,69 +58,3 @@ To install Glance, see the Newton Image service install guide for each distribut
 - `Ubuntu <https://docs.openstack.org/newton/install-guide-ubuntu/glance.html>`_
 - `CentOS and RHEL <https://docs.openstack.org/newton/install-guide-rdo/glance.html>`_
 - `openSUSE and SUSE Linux Enterprise <https://docs.openstack.org/newton/install-guide-obs/glance.html>`_
-
-Developer reference
-~~~~~~~~~~~~~~~~~~~
-
-.. toctree::
-   :maxdepth: 2
-
-   architecture
-   database_architecture
-   database_migrations
-   domain_model
-   domain_implementation
-
-User guide
-~~~~~~~~~~
-
-.. TODO - move this content to docs.o.o
-
-.. toctree::
-   :maxdepth: 2
-
-   identifiers
-   statuses
-   formats
-   common-image-properties
-   metadefs-concepts
-   glanceapi
-   glanceclient
-   glancemetadefcatalogapi
-   signature
-   api/modules
-
-Administration guide
-~~~~~~~~~~~~~~~~~~~~
-
-.. TODO - move this content to docs.o.o
-
-.. toctree::
-   :maxdepth: 2
-
-   tasks
-   configuring
-   sample-configuration
-   authentication
-   policies
-   flows
-   property-protections
-   opts/index
-   requirements
-   apache-httpd
-
-Operating Glance
-~~~~~~~~~~~~~~~~
-
-.. TODO - move this content to docs.o.o
-
-.. toctree::
-   :maxdepth: 1
-
-   controllingservers
-   db
-   rollingupgrades
-   cache
-   notifications
-
-

doc/source/user/index.rst

@@ -0,0 +1,16 @@
+============
+ User guide
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   identifiers
+   statuses
+   formats
+   common-image-properties
+   metadefs-concepts
+   glanceapi
+   glanceclient
+   glancemetadefcatalogapi
+   signature

setup.cfg

@@ -86,3 +86,4 @@ output_file = glance/locale/glance.pot
 
 [pbr]
 autodoc_tree_index_modules = True
+api_doc_dir = contributor/api