From 10178e28886b870753531a61fea22200d844d0c1 Mon Sep 17 00:00:00 2001 From: KATO Tomoyuki Date: Sun, 10 Jul 2016 08:54:58 +0900 Subject: [PATCH] [contributor] reorganize blueprints and specifications Change-Id: I101b74cc4c40da8d0515ec4ab9d940dc239287b7 Implements: blueprint contributor-guide-reorg --- .../source/blueprints-and-specs.rst | 197 ++++++++++++++++-- .../source/content-specs.rst | 175 ---------------- doc/contributor-guide/source/index.rst | 3 +- 3 files changed, 180 insertions(+), 195 deletions(-) delete mode 100644 doc/contributor-guide/source/content-specs.rst diff --git a/doc/contributor-guide/source/blueprints-and-specs.rst b/doc/contributor-guide/source/blueprints-and-specs.rst index 000aef928b..f724423dbe 100644 --- a/doc/contributor-guide/source/blueprints-and-specs.rst +++ b/doc/contributor-guide/source/blueprints-and-specs.rst @@ -1,16 +1,22 @@ -============================= -Blueprints and specifications -============================= +.. _content-specs: -The Documentation team uses specifications in the `docs-specs repository`_ to -maintain large changes. Approved specifications are published at -`Documentation Program Specifications`_. For tracking purposes, a blueprint is -created for each specification. +===================== +Content specification +===================== + +Blueprints and specifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Documentation team uses specifications in the `docs-specs repository +`_ to maintain large +changes. Approved specifications are published at `Documentation Program +Specifications `_. +For tracking purposes, a blueprint is created for each specification. Use blueprints and specifications: -* When adding large sections to an existing document to ensure involvement of - the core doc team. +* When adding large sections to an existing document to ensure involvement + of the docs core team. * When adding an entirely new deliverable to the docs project. * For any work that requires both content and tooling changes, such as addition of the API reference site. @@ -18,9 +24,11 @@ Use blueprints and specifications: * For automation work that needs to be designed prior to proposing a patch. * For work that should definitely be discussed at a summit. -A specification needs two +2 votes from the docs-specs-core team. See the -current list of `docs-specs core team`_. For more information, see: -`Blueprints and specifications`_. +A specification needs two +2 votes from the docs-specs-core team. +See the current list of `docs-specs core team +`_. +For more information, see `Blueprints and specifications +`_. Use bugs against openstack-manuals or openstack-api-site: @@ -29,10 +37,163 @@ Use bugs against openstack-manuals or openstack-api-site: * To add content that is just missing. * For known errors in a document. -For more information, see: :ref:`doc_bugs`. +For more information, see :ref:`doc_bugs`. -.. Links -.. _`docs-specs repository`: http://git.openstack.org/cgit/openstack/docs-specs/ -.. _`Documentation Program Specifications`: http://specs.openstack.org/openstack/docs-specs/ -.. _`docs-specs core team`: https://review.openstack.org/#/admin/groups/384,members -.. _`Blueprints and specifications`: https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs +Release-specific documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Installation Guides, Configuration Reference, and Networking Guide +are released at release time, with draft material published to +https://docs.openstack.org/draft/draft-index.html. +The rest of the guides are continuously released. + +To patch for the release-specific documentation, you should generally patch to +master branch with "backport: xxxx" (for example, backport: kilo) in the commit +message. + +Installation Guides +------------------- + +The OpenStack Installation Guide describes a manual install process for +multiple distributions based on the following packaging systems: + +* `Installation Guide for openSUSE and SUSE Linux Enterprise Server + `_ +* `Installation Guide for Red Hat Enterprise Linux and CentOS + `_ +* `Installation Guide for Ubuntu + `_ + +Guides for deployers and administrators +--------------------------------------- + +* `OpenStack Configuration Reference + `_: + Contains a reference listing of all configuration options for OpenStack + services by release version. +* `OpenStack Networking Guide + `_: + This guide targets OpenStack administrators seeking to deploy and manage + OpenStack Networking (neutron). + +Continuously released documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These guides cover multiple versions and we follow the general +`release information `_. +The guides cover the latest two versions, for +example Juno and Kilo. The following exceptions apply: + +* Operations Guide: Icehouse target, revised specifically to target that + release +* HA Guide: Updated last at Havana timeframe, still needs updates + +Guides for deployers and administrators +--------------------------------------- + +* `OpenStack Architecture Design Guide + `_: + Contains information on how to plan, design and architect + an OpenStack cloud. +* `OpenStack Administrator Guide `_: + Contains how-to information for managing an OpenStack cloud as needed for + your use cases, such as storage, computing, or software-defined-networking. +* `OpenStack High Availability Guide `_: + Describes potential strategies for making your OpenStack services and + related controllers and data stores highly available. +* `OpenStack Security Guide `_: + Provide best practices and conceptual + information about securing an OpenStack cloud. +* `Virtual Machine Image Guide `_: + Shows you how to obtain, create, and modify virtual machine images that + are compatible with OpenStack. + +Guides for end users +-------------------- + +* `OpenStack End User Guide `_: + Shows OpenStack end users how to create and manage resources in an + OpenStack cloud with the OpenStack dashboard and OpenStack client commands. +* `OpenStack API Guide + `_: + A brief overview of how to send REST API requests to endpoints for + OpenStack services. +* `OpenStack Command-Line Interface Reference + `_: + Automatically generates help text for CLI commands and subcommands. + +API documentation +----------------- + +* `Complete API Reference `_: + Complete reference listing of OpenStack REST APIs + with example requests and responses. +* `API specifications `_: + Within project's specification repos, some have opted + to document API specifications, such as Identity. +* `Object Storage API v1 + `_ + +Guides for contributors +----------------------- + +* `Infrastructure User Manual `_: + Reference documentation for tools and processes used for all + contributors to OpenStack projects. It includes instructions on how + to create all the necessary accounts, setup development environment, + use gerrit review workflow. The manual also covers more + advanced topics, like how to create new git repositories. The manual is + maintained by the OpenStack Infrastructure team. + +Licenses +~~~~~~~~ + +This section shows the license indicators as of March 20, 2015. + +* OpenStack Architecture Design Guide: Apache 2.0 and CC-by-sa 3.0 +* OpenStack Administrator Guide: Apache 2.0 and CC-by-sa 3.0 + +* OpenStack Install Guides (all): Apache 2.0 +* OpenStack High Availability Guide: Apache 2.0 +* OpenStack Configuration Reference: Apache 2.0 +* OpenStack Networking Guide: Apache 2.0 + +* OpenStack Security Guide: CC-by 3.0 +* Virtual Machine Image Guide: CC-by 3.0 +* OpenStack Operations Guide: CC-by 3.0 +* OpenStack End User Guide: CC-by 3.0 +* Command-Line Interface Reference: CC-by 3.0 + +* Contributor dev docs (docs.openstack.org/developer/): none + indicated in output; Apache 2.0 in repo +* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo +* API Complete Reference: none indicated in output; Apache 2.0 in repo + +* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo + +What to do to make more consistent output: + +* OpenStack Architecture Design Guide: Apache 2.0 and CC-by 3.0 +* OpenStack Administrator Guide: Apache 2.0 and CC-by 3.0 +* OpenStack Install Guides (all): Apache 2.0 and CC-by 3.0 +* OpenStack High Availability Guide: Apache 2.0 and CC-by 3.0 +* OpenStack Security Guide: CC-by 3.0 +* Virtual Machine Image Guide: CC-by 3.0 +* OpenStack Operations Guide: CC-by 3.0 +* OpenStack End User Guide: CC-by 3.0 + +These guides are created by "scraping" code: + +* OpenStack Configuration Reference: Apache 2.0 and CC-by 3.0 +* Command-Line Interface Reference: Apache 2.0 and CC-by 3.0 + +These guides have no indicator in output: + +* Contributor dev docs (docs.openstack.org/developer/): none + indicated in output; Apache 2.0 in repo +* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo +* API Complete Reference: none indicated in output; Apache 2.0 in repo + +This guide has a review in place to get a license indicator in output: + +* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo diff --git a/doc/contributor-guide/source/content-specs.rst b/doc/contributor-guide/source/content-specs.rst deleted file mode 100644 index 244b06ae5c..0000000000 --- a/doc/contributor-guide/source/content-specs.rst +++ /dev/null @@ -1,175 +0,0 @@ - -.. _content-specs: - -===================== -Content specification -===================== - -Release-specific documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Installation Guides, Configuration Reference, and Networking Guide -are released at release time, with draft material published to -docs.openstack.org/draft/draft-index.html. The rest of the guides are -continuously released. - -To patch for the release-specific documentation, you should generally patch to -master branch with "backport: xxxx" (for example, backport: kilo) in the commit -message. - -Installation Guides -------------------- - -The OpenStack Installation Guide describes a manual install process for -multiple distributions based on the following packaging systems: - -* `Installation Guide for openSUSE and SUSE Linux Enterprise Server`_ -* `Installation Guide for Red Hat Enterprise Linux and CentOS`_ -* `Installation Guide for Ubuntu`_ - -Guides for deployers and administrators ---------------------------------------- - -* `OpenStack Configuration Reference`_: Contains a reference listing of all - configuration options for core and integrated OpenStack services by release - version. -* `OpenStack Networking Guide`_: This guide targets OpenStack administrators - seeking to deploy and manage OpenStack Networking (neutron). - -Continuously released documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These guides cover multiple versions and we follow the general -`release information`_. The guides cover the latest two versions, for -example Juno and Kilo. The following exceptions apply: - -* Operations Guide: Icehouse target, revised specifically to target that - release -* HA Guide: Updated last at Havana timeframe, still needs updates - -Guides for deployers and administrators ---------------------------------------- - -* `OpenStack Architecture Design Guide`_: Contains information on how to plan, - design and architect an OpenStack cloud. -* `OpenStack Administrator Guide`_: Contains how-to information for - managing an OpenStack cloud as needed for your use cases, such as storage, - computing, or software-defined-networking. -* `OpenStack High Availability Guide`_: Describes potential strategies for - making your OpenStack services and related controllers and data stores - highly available. -* `OpenStack Security Guide`_: Provide best practices and conceptual - information about securing an OpenStack cloud. -* `Virtual Machine Image Guide`_: Shows you how to obtain, create, and modify - virtual machine images that are compatible with OpenStack. - -Guides for end users --------------------- - -* `OpenStack End User Guide`_: Shows OpenStack end users how to create and - manage resources in an OpenStack cloud with the OpenStack dashboard and - OpenStack client commands. -* `OpenStack API Guide`_: A brief overview of how to send REST API - requests to endpoints for OpenStack services. -* `Command-Line Interface Reference`_: Automatically generates help text for - CLI commands and subcommands. - -API documentation ------------------ - -* `Complete API Reference`_: Complete reference listing of OpenStack REST APIs - with example requests and responses. -* `API specifications`_: Within project's specification repos, some have opted - to document API specifications, such as Identity. -* `Object Storage API v1`_ - -Guides for contributors ------------------------ - -* `Infrastructure User Manual`_: Reference documentation for tools and - processes used for all contributors to OpenStack projects. It includes - instructions on how to create all the necessary accounts, setup development - environment, use gerrit review workflow. The manual also covers more - advanced topics, like how to create new git repositories. The manual is - maintained by the OpenStack Infrastructure team. - -Licenses --------- - -This section shows the license indicators as of March 20, 2015. - -* OpenStack Architecture Design Guide: Apache 2.0 and CC-by-sa 3.0 -* OpenStack Administrator Guide: Apache 2.0 and CC-by-sa 3.0 - -* OpenStack Install Guides (all): Apache 2.0 -* OpenStack High Availability Guide: Apache 2.0 -* OpenStack Configuration Reference: Apache 2.0 -* OpenStack Networking Guide: Apache 2.0 - -* OpenStack Security Guide: CC-by 3.0 -* Virtual Machine Image Guide: CC-by 3.0 -* OpenStack Operations Guide: CC-by 3.0 -* OpenStack End User Guide: CC-by 3.0 -* Command-Line Interface Reference: CC-by 3.0 - -* Contributor dev docs (docs.openstack.org/developer/): none - indicated in output; Apache 2.0 in repo -* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo -* API Complete Reference: none indicated in output; Apache 2.0 in repo - -* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo - -What to do to make more consistent output: - -* OpenStack Architecture Design Guide: Apache 2.0 and CC-by 3.0 -* OpenStack Administrator Guide: Apache 2.0 and CC-by 3.0 -* OpenStack Install Guides (all): Apache 2.0 and CC-by 3.0 -* OpenStack High Availability Guide: Apache 2.0 and CC-by 3.0 -* OpenStack Security Guide: CC-by 3.0 -* Virtual Machine Image Guide: CC-by 3.0 -* OpenStack Operations Guide: CC-by 3.0 -* OpenStack End User Guide: CC-by 3.0 - -These guides are created by "scraping" code: - -* OpenStack Configuration Reference: Apache 2.0 and CC-by 3.0 -* Command-Line Interface Reference: Apache 2.0 and CC-by 3.0 - -These guides have no indicator in output: - -* Contributor dev docs (docs.openstack.org/developer/): none - indicated in output; Apache 2.0 in repo -* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo -* API Complete Reference: none indicated in output; Apache 2.0 in repo - -This guide has a review in place to get a license indicator in output: - -* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo - - -.. Links -.. _`Installation Guide for openSUSE and SUSE Linux Enterprise Server`: http://docs.openstack.org/mitaka/install-guide-obs/ -.. _`Installation Guide for Red Hat Enterprise Linux and CentOS`: http://docs.openstack.org/mitaka/install-guide-rdo/ -.. _`Installation Guide for Ubuntu`: http://docs.openstack.org/mitaka/install-guide-ubuntu/ - -.. _`OpenStack Configuration Reference`: http://docs.openstack.org/mitaka/config-reference/ - -.. _`OpenStack Networking Guide`: http://docs.openstack.org/mitaka/networking-guide/ - -.. _`release information`: https://wiki.openstack.org/wiki/Releases - -.. _`OpenStack Architecture Design Guide`: http://docs.openstack.org/arch-design/ -.. _`OpenStack Administrator Guide`: http://docs.openstack.org/admin-guide/index.html -.. _`OpenStack High Availability Guide`: http://docs.openstack.org/ha-guide/index.html -.. _`OpenStack Security Guide`: http://docs.openstack.org/sec/ -.. _`Virtual Machine Image Guide`: http://docs.openstack.org/image-guide/ - -.. _`OpenStack End User Guide`: http://docs.openstack.org/user-guide/index.html -.. _`OpenStack API Guide`: http://developer.openstack.org/api-guide/quick-start/ -.. _`Command-Line Interface Reference`: http://docs.openstack.org/cli-reference/ - -.. _`Complete API Reference`: http://developer.openstack.org/api-ref.html -.. _`API specifications`: http://specs.openstack.org/ -.. _`Object Storage API v1`: http://docs.openstack.org/developer/swift/#object-storage-v1-rest-api-documentation - -.. _`Infrastructure User Manual`: http://docs.openstack.org/infra/manual/ diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 05baf8f2bb..2cc8415cea 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -18,12 +18,11 @@ Contents quickstart.rst additional-git-workflow.rst - blueprints-and-specs.rst doc-bugs.rst docs-review.rst team-structure.rst docs-structure.rst - content-specs.rst + blueprints-and-specs.rst api-guides.rst project-install-guide topic-structure.rst