diff --git a/.gitignore b/.gitignore index 79c31ed06f..681ad1afd1 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/source/apache-httpd.rst b/doc/source/admin/apache-httpd.rst similarity index 100% rename from doc/source/apache-httpd.rst rename to doc/source/admin/apache-httpd.rst diff --git a/doc/source/authentication.rst b/doc/source/admin/authentication.rst similarity index 100% rename from doc/source/authentication.rst rename to doc/source/admin/authentication.rst diff --git a/doc/source/cache.rst b/doc/source/admin/cache.rst similarity index 100% rename from doc/source/cache.rst rename to doc/source/admin/cache.rst diff --git a/doc/source/controllingservers.rst b/doc/source/admin/controllingservers.rst similarity index 100% rename from doc/source/controllingservers.rst rename to doc/source/admin/controllingservers.rst diff --git a/doc/source/db-sqlalchemy-migrate.rst b/doc/source/admin/db-sqlalchemy-migrate.rst similarity index 100% rename from doc/source/db-sqlalchemy-migrate.rst rename to doc/source/admin/db-sqlalchemy-migrate.rst diff --git a/doc/source/db.rst b/doc/source/admin/db.rst similarity index 100% rename from doc/source/db.rst rename to doc/source/admin/db.rst diff --git a/doc/source/flows.rst b/doc/source/admin/flows.rst similarity index 100% rename from doc/source/flows.rst rename to doc/source/admin/flows.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 0000000000..eaec7b1873 --- /dev/null +++ b/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 diff --git a/doc/source/notifications.rst b/doc/source/admin/notifications.rst similarity index 100% rename from doc/source/notifications.rst rename to doc/source/admin/notifications.rst diff --git a/doc/source/policies.rst b/doc/source/admin/policies.rst similarity index 100% rename from doc/source/policies.rst rename to doc/source/admin/policies.rst diff --git a/doc/source/property-protections.rst b/doc/source/admin/property-protections.rst similarity index 100% rename from doc/source/property-protections.rst rename to doc/source/admin/property-protections.rst diff --git a/doc/source/requirements.rst b/doc/source/admin/requirements.rst similarity index 100% rename from doc/source/requirements.rst rename to doc/source/admin/requirements.rst diff --git a/doc/source/rollingupgrades.rst b/doc/source/admin/rollingupgrades.rst similarity index 100% rename from doc/source/rollingupgrades.rst rename to doc/source/admin/rollingupgrades.rst diff --git a/doc/source/tasks.rst b/doc/source/admin/tasks.rst similarity index 100% rename from doc/source/tasks.rst rename to doc/source/admin/tasks.rst diff --git a/doc/source/man/footer.rst b/doc/source/cli/footer.rst similarity index 100% rename from doc/source/man/footer.rst rename to doc/source/cli/footer.rst diff --git a/doc/source/man/general_options.rst b/doc/source/cli/general_options.rst similarity index 100% rename from doc/source/man/general_options.rst rename to doc/source/cli/general_options.rst diff --git a/doc/source/man/glanceapi.rst b/doc/source/cli/glanceapi.rst similarity index 100% rename from doc/source/man/glanceapi.rst rename to doc/source/cli/glanceapi.rst diff --git a/doc/source/man/glancecachecleaner.rst b/doc/source/cli/glancecachecleaner.rst similarity index 100% rename from doc/source/man/glancecachecleaner.rst rename to doc/source/cli/glancecachecleaner.rst diff --git a/doc/source/man/glancecachemanage.rst b/doc/source/cli/glancecachemanage.rst similarity index 100% rename from doc/source/man/glancecachemanage.rst rename to doc/source/cli/glancecachemanage.rst diff --git a/doc/source/man/glancecacheprefetcher.rst b/doc/source/cli/glancecacheprefetcher.rst similarity index 100% rename from doc/source/man/glancecacheprefetcher.rst rename to doc/source/cli/glancecacheprefetcher.rst diff --git a/doc/source/man/glancecachepruner.rst b/doc/source/cli/glancecachepruner.rst similarity index 100% rename from doc/source/man/glancecachepruner.rst rename to doc/source/cli/glancecachepruner.rst diff --git a/doc/source/man/glancecontrol.rst b/doc/source/cli/glancecontrol.rst similarity index 100% rename from doc/source/man/glancecontrol.rst rename to doc/source/cli/glancecontrol.rst diff --git a/doc/source/man/glancemanage.rst b/doc/source/cli/glancemanage.rst similarity index 100% rename from doc/source/man/glancemanage.rst rename to doc/source/cli/glancemanage.rst diff --git a/doc/source/man/glanceregistry.rst b/doc/source/cli/glanceregistry.rst similarity index 100% rename from doc/source/man/glanceregistry.rst rename to doc/source/cli/glanceregistry.rst diff --git a/doc/source/man/glancereplicator.rst b/doc/source/cli/glancereplicator.rst similarity index 100% rename from doc/source/man/glancereplicator.rst rename to doc/source/cli/glancereplicator.rst diff --git a/doc/source/man/glancescrubber.rst b/doc/source/cli/glancescrubber.rst similarity index 100% rename from doc/source/man/glancescrubber.rst rename to doc/source/cli/glancescrubber.rst diff --git a/doc/source/man/header.rst b/doc/source/cli/header.rst similarity index 100% rename from doc/source/man/header.rst rename to doc/source/cli/header.rst diff --git a/doc/source/man/openstack_options.rst b/doc/source/cli/openstack_options.rst similarity index 100% rename from doc/source/man/openstack_options.rst rename to doc/source/cli/openstack_options.rst diff --git a/doc/source/configuring.rst b/doc/source/configuration/configuring.rst similarity index 99% rename from doc/source/configuring.rst rename to doc/source/configuration/configuring.rst index 6c62543f49..0d45b46651 100644 --- a/doc/source/configuring.rst +++ b/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=`` + Optional. Default: ``True`` ``enable_v2_registry=`` + 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 `_. ``[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=`` + 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=`` + Optional. Default: ``True`` ``enable_v2_api=`` + 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=`` + 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=`` + 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=`` + 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=`` + 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=`` + 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=`` + 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=`` + Optional. Default: ``sha256`` Configuring http_keepalive option --------------------------------- ``http_keepalive=`` + 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=`` + Optional. Default: ``ami,ari,aki,vhd,vhdx,vmdk,raw,qcow2,vdi,iso,ploop`` diff --git a/doc/source/opts/glance_api.rst b/doc/source/configuration/glance_api.rst similarity index 100% rename from doc/source/opts/glance_api.rst rename to doc/source/configuration/glance_api.rst diff --git a/doc/source/opts/glance_cache.rst b/doc/source/configuration/glance_cache.rst similarity index 100% rename from doc/source/opts/glance_cache.rst rename to doc/source/configuration/glance_cache.rst diff --git a/doc/source/opts/glance_manage.rst b/doc/source/configuration/glance_manage.rst similarity index 100% rename from doc/source/opts/glance_manage.rst rename to doc/source/configuration/glance_manage.rst diff --git a/doc/source/opts/glance_registry.rst b/doc/source/configuration/glance_registry.rst similarity index 100% rename from doc/source/opts/glance_registry.rst rename to doc/source/configuration/glance_registry.rst diff --git a/doc/source/opts/glance_scrubber.rst b/doc/source/configuration/glance_scrubber.rst similarity index 100% rename from doc/source/opts/glance_scrubber.rst rename to doc/source/configuration/glance_scrubber.rst diff --git a/doc/source/opts/index.rst b/doc/source/configuration/index.rst similarity index 100% rename from doc/source/opts/index.rst rename to doc/source/configuration/index.rst diff --git a/doc/source/sample-configuration.rst b/doc/source/configuration/sample-configuration.rst similarity index 67% rename from doc/source/sample-configuration.rst rename to doc/source/configuration/sample-configuration.rst index f6dd5f1881..8cc8f66891 100644 --- a/doc/source/sample-configuration.rst +++ b/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 diff --git a/doc/source/architecture.rst b/doc/source/contributor/architecture.rst similarity index 98% rename from doc/source/architecture.rst rename to doc/source/contributor/architecture.rst index 0eaf22797a..a587e84dfb 100644 --- a/doc/source/architecture.rst +++ b/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. diff --git a/doc/source/contributing/blueprints.rst b/doc/source/contributor/blueprints.rst similarity index 100% rename from doc/source/contributing/blueprints.rst rename to doc/source/contributor/blueprints.rst diff --git a/doc/source/database_architecture.rst b/doc/source/contributor/database_architecture.rst similarity index 99% rename from doc/source/database_architecture.rst rename to doc/source/contributor/database_architecture.rst index 65b98cbd2c..8a4d2d0e12 100644 --- a/doc/source/database_architecture.rst +++ b/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. diff --git a/doc/source/database_migrations.rst b/doc/source/contributor/database_migrations.rst similarity index 99% rename from doc/source/database_migrations.rst rename to doc/source/contributor/database_migrations.rst index 24bc3a0a57..fe68202a3e 100644 --- a/doc/source/database_migrations.rst +++ b/doc/source/contributor/database_migrations.rst @@ -340,8 +340,8 @@ References ========== .. [GSPEC1] `Database Strategy for Rolling Upgrades `_ -.. [GSPEC2] `Glance Alembic Migrations +.. [GSPEC2] `Glance Alembic Migrations Spec `_ -.. [GMIGS1] `Glance Alembic Migrations +.. [GMIGS1] `Glance Alembic Migrations Implementation `_ .. [ALMBC] `Alembic Operations `_ diff --git a/doc/source/contributing/documentation.rst b/doc/source/contributor/documentation.rst similarity index 100% rename from doc/source/contributing/documentation.rst rename to doc/source/contributor/documentation.rst diff --git a/doc/source/domain_implementation.rst b/doc/source/contributor/domain_implementation.rst similarity index 99% rename from doc/source/domain_implementation.rst rename to doc/source/contributor/domain_implementation.rst index 8d78533013..5b04a37214 100644 --- a/doc/source/domain_implementation.rst +++ b/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, diff --git a/doc/source/domain_model.rst b/doc/source/contributor/domain_model.rst similarity index 100% rename from doc/source/domain_model.rst rename to doc/source/contributor/domain_model.rst diff --git a/doc/source/contributing/index.rst b/doc/source/contributor/index.rst similarity index 86% rename from doc/source/contributing/index.rst rename to doc/source/contributor/index.rst index 068dfc3a1f..8cec9d76ac 100644 --- a/doc/source/contributing/index.rst +++ b/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 `_. +Developer reference +------------------- + +.. toctree:: + :maxdepth: 2 + + architecture + database_architecture + database_migrations + domain_model + domain_implementation + api/modules + Policies -------- .. toctree:: diff --git a/doc/source/contributing/minor-code-changes.rst b/doc/source/contributor/minor-code-changes.rst similarity index 100% rename from doc/source/contributing/minor-code-changes.rst rename to doc/source/contributor/minor-code-changes.rst diff --git a/doc/source/contributing/refreshing-configs.rst b/doc/source/contributor/refreshing-configs.rst similarity index 100% rename from doc/source/contributing/refreshing-configs.rst rename to doc/source/contributor/refreshing-configs.rst diff --git a/doc/source/contributing/release-cpl.rst b/doc/source/contributor/release-cpl.rst similarity index 100% rename from doc/source/contributing/release-cpl.rst rename to doc/source/contributor/release-cpl.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 9c1329e742..c061c09a99 100644 --- a/doc/source/index.rst +++ b/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 `_ - `CentOS and RHEL `_ - `openSUSE and SUSE Linux Enterprise `_ - -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 - - diff --git a/doc/source/installing.rst b/doc/source/install/index.rst similarity index 100% rename from doc/source/installing.rst rename to doc/source/install/index.rst diff --git a/doc/source/common-image-properties.rst b/doc/source/user/common-image-properties.rst similarity index 100% rename from doc/source/common-image-properties.rst rename to doc/source/user/common-image-properties.rst diff --git a/doc/source/formats.rst b/doc/source/user/formats.rst similarity index 100% rename from doc/source/formats.rst rename to doc/source/user/formats.rst diff --git a/doc/source/glanceapi.rst b/doc/source/user/glanceapi.rst similarity index 100% rename from doc/source/glanceapi.rst rename to doc/source/user/glanceapi.rst diff --git a/doc/source/glanceclient.rst b/doc/source/user/glanceclient.rst similarity index 100% rename from doc/source/glanceclient.rst rename to doc/source/user/glanceclient.rst diff --git a/doc/source/glancemetadefcatalogapi.rst b/doc/source/user/glancemetadefcatalogapi.rst similarity index 100% rename from doc/source/glancemetadefcatalogapi.rst rename to doc/source/user/glancemetadefcatalogapi.rst diff --git a/doc/source/identifiers.rst b/doc/source/user/identifiers.rst similarity index 100% rename from doc/source/identifiers.rst rename to doc/source/user/identifiers.rst diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000000..f798f14538 --- /dev/null +++ b/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 diff --git a/doc/source/metadefs-concepts.rst b/doc/source/user/metadefs-concepts.rst similarity index 100% rename from doc/source/metadefs-concepts.rst rename to doc/source/user/metadefs-concepts.rst diff --git a/doc/source/signature.rst b/doc/source/user/signature.rst similarity index 100% rename from doc/source/signature.rst rename to doc/source/user/signature.rst diff --git a/doc/source/statuses.rst b/doc/source/user/statuses.rst similarity index 100% rename from doc/source/statuses.rst rename to doc/source/user/statuses.rst diff --git a/setup.cfg b/setup.cfg index dab829f0f7..859431e70b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -86,3 +86,4 @@ output_file = glance/locale/glance.pot [pbr] autodoc_tree_index_modules = True +api_doc_dir = contributor/api