From 93daffe410e84e2a7101dc204ac923ba2eebd1d1 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Fri, 26 Aug 2016 13:47:00 -0500 Subject: [PATCH] Updates the "API Quick Start" to become a better landing for all API docs - Uses new openstackdocstheme configured with the api_ref sidebar. - Updates intro text to ensure we get the same text as what was in the developer.openstack.org/api_ref.html landing page. - With these changes we should be able to completely remove and redirect developer.openstack.org/api_ref.html to http://developer.openstack.org/api-guide/quick-start/. Change-Id: I5ea811aac3b34774b9cdde6c0d788b12b97977bb --- api-quick-start/setup.cfg | 6 +- api-quick-start/source/conf.py | 24 +++++--- api-quick-start/source/index.rst | 98 ++++++++++++++++++++++++++++---- test-requirements.txt | 2 +- 4 files changed, 107 insertions(+), 23 deletions(-) diff --git a/api-quick-start/setup.cfg b/api-quick-start/setup.cfg index d3a98cd09..0d5436295 100644 --- a/api-quick-start/setup.cfg +++ b/api-quick-start/setup.cfg @@ -1,11 +1,11 @@ [metadata] -name = OpenStack API Quick Start -summary = OpenStack API Quick Start +name = OpenStack API Documentation +summary = OpenStack API Documentation description-file = README.rst author = OpenStack Documentation author-email = openstack-docs@lists.openstack.org -home-page = http://docs.openstack.org/ +home-page = http://developer.openstack.org/ classifier = Intended Audience :: Developers License :: OSI Approved :: Apache Software License diff --git a/api-quick-start/source/conf.py b/api-quick-start/source/conf.py index 5c12e397c..0f98a4f74 100644 --- a/api-quick-start/source/conf.py +++ b/api-quick-start/source/conf.py @@ -52,9 +52,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'API-Quick-Start' +project = u'Openstack-API-Documentation' bug_tag = u'api-site' -copyright = u'2015, OpenStack contributors' +copyright = u'2016, OpenStack contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -131,6 +131,14 @@ html_theme = 'openstackdocs' # documentation. # html_theme_options = {} +# To use the API Reference sidebar dropdown menu, +# uncomment the html_theme_options parameter. The theme +# variable, sidebar_dropdown, should be set to `api_ref`. +# Otherwise, the list of links for the User and Ops docs +# appear in the sidebar dropdown menu. +html_theme_options = {"sidebar_dropdown": "api_ref", + "sidebar_mode": "toc"} + # Add any paths that contain custom themes here, relative to this directory. html_theme_path = [openstackdocstheme.get_html_theme_path()] @@ -206,7 +214,7 @@ html_show_sourcelink = False # html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'API-Quick-Start' +htmlhelp_basename = 'OpenStack-API-Documentation' # If true, publish source files html_copy_source = False @@ -228,7 +236,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'FirstApp.tex', u'FirstApp Documentation', + ('index', 'OpenStackAPI.tex', u'OpenStack API Documentation', u'OpenStack Doc Team', 'manual'), ] @@ -258,7 +266,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'api-quick-start', u'API Quick Start Documentation', + ('index', 'openstack-api-documentation', u'OpenStack API Documentation', [u'OpenStack Doc Team'], 1) ] @@ -272,8 +280,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'api-quick-start', u'API Quick Start Documentation', - u'OpenStack Doc Team', 'APIQuickStart', 'Describes basic OpenStack API concepts.', + ('index', 'openstack-api-documentation', u'OpenStack API Documentation', + u'OpenStack Doc Team', 'OpenStackAPIDocs', 'Describes OpenStack API reference and concepts.', 'Miscellaneous'), ] @@ -298,6 +306,6 @@ locale_dirs = ['locale/'] # -- Options for PDF output -------------------------------------------------- pdf_documents = [ - ('index', u'api-quick-start', u'API Quick Start Documentation', + ('index', u'openstack-api-documentation', u'OpenStack API Documentation', u'OpenStack contributors') ] diff --git a/api-quick-start/source/index.rst b/api-quick-start/source/index.rst index 2668afa37..407a34a00 100644 --- a/api-quick-start/source/index.rst +++ b/api-quick-start/source/index.rst @@ -1,13 +1,89 @@ -=================== -OpenStack API Guide -=================== +=========================== +OpenStack API Documentation +=========================== -Although you install each OpenStack service separately, the OpenStack -services work together to meet your cloud needs: Identity, Compute, -Images, Block Storage, Networking (neutron), Object Storage, Databases, and -Metering. With the `TryStack `__ OpenStack +Use the OpenStack APIs to launch server instances, create images, assign +metadata to instances and images, create storage containers and objects, and +complete other actions in your OpenStack cloud. + +Current API versions +-------------------- + +`Bare Metal API v1 `__ (microversions) + +`Block Storage API v2 `__ + +`Clustering API v1 `__ + +`Compute API `__ (microversions) + +`Data Processing v1.1 `__ + +`Database Service API v1.0 `__ + +`Domain Name Server (DNS) API v2 `__ + +`Identity API v3 `__ + +`Identity API v3 extensions `__ + +`Image service API v2 `__ + +`Networking API v2.0 `__ + +`Object Storage API v1 `__ + +`Orchestration API v1 `__ + +`Shared File Systems API v2 `__ (microversions) + +.. note:: The Shared File Systems API v1 is functionally identical to the + Shared File Systems API v2. Subsequent API v2 microversions, such as v2.1, + differ from API v1. + +Supported API versions +---------------------- + +`Block Storage API v1 `__ + +`Image service API v1 `__ + +Deprecated API versions +----------------------- + +`Identity API v2.0 `__ + +`Identity admin API v2.0 `__ + +`Identity API v2.0 extensions `__ + +.. todo: telemetry link + +The API status reflects the state of the endpoint on the service. + +* Current indicates a stable version that is up-to-date, recent, and might + receive future versions. This endpoint should be prioritized over all + others. +* Supported is a stable version that is available on the server. However, it + is not likely the most recent available and might not be updated or might + be deprecated at some time in the future. +* Deprecated is a stable version that is still available but is being + deprecated and might be removed in the future. +* Experimental is not a stable version. This version is under development or + contains features that are otherwise subject to change. For more + information about API status values and version information, see + `Version Discovery `__. +* Microversions indicates that the API follows a `pattern established by + the Compute service `__ to + enable small, documented changes to the API on a resource-by-resource + basis. + +API quick-start examples +------------------------ + +With the `TryStack `__ OpenStack installation, these services work together in the background of the -installation. +installation, and many of these examples work on TryStack. After you authenticate through Identity, you can use the other OpenStack APIs to create and manage resources in your OpenStack cloud. You can @@ -46,11 +122,11 @@ To begin sending API requests, use one of the following methods: SDK `__ in the *OpenStack End User Guide*. -Learn more ----------- - .. toctree:: + :maxdepth: 2 api-quick-start + + diff --git a/test-requirements.txt b/test-requirements.txt index 460416abc..721951944 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -7,6 +7,6 @@ doc8 # Apache-2.0 Pygments # At least 1.3 is required for dedent in code blocks. Capped to 1.3 to not get an automatic update to any newer versions. sphinx>=1.3,!=1.3b1,<1.4 -openstackdocstheme>=1.4.0 +openstackdocstheme>=1.5.0 nwdiag sphinxcontrib-nwdiag