Update sphinx doc formatting and toctrees

Create index pages with toctree entries to load the existing
documents so they are all linked together.

Add titles to some of the documents that did not have them to
make them work with sphinx.

Change-Id: I0d44cfe1a75ab7df07e0efc989eb7cf161d9bf78

.gitignore

@@ -0,0 +1,4 @@
+.tox
+doc/build
+*.egg-info
+pbr*.egg

doc/source/index.rst

@@ -1 +0,0 @@
-../../README.rst

doc/source/index.rst

@@ -0,0 +1,19 @@
+====================================================
+ OpenStack Technical Committee Governance Documents
+====================================================
+
+These pages contain OpenStack Technical Committee reference documents
+and track official resolutions voted by the committee.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   reference/index
+   resolutions/index
+
+.. seealso::
+
+  See the TechnicalCommittee_ page in the wiki for details.
+
+.. _TechnicalCommittee: https://wiki.openstack.org/wiki/Governance/TechnicalCommittee

doc/source/reference

@@ -1 +1 @@
-../../reference/
+../../reference

doc/source/resolutions

@@ -0,0 +1 @@
+../../resolutions

reference/charter.rst

@@ -1,6 +1,6 @@
-=========================================
- OpenStack Technical Committee charter
-=========================================
+=======================================
+ OpenStack Technical Committee Charter
+=======================================
 
 Mission
 =======

reference/incubation-integration-requirements

@@ -1,145 +0,0 @@
-= Minimal requirements for incubation and integrated status =
-
-== Incubation ==
-
-The TC will evaluate the project scope and its complementarity with existing
-integrated projects and other official programs, look into the project
-technical choices, and check a number of requirements, including (but not
-limited to):
-
-* Scope
-** Project must have a clear and defined scope.
-** Project's scope should represent a measured progression for OpenStack as a
-   whole.
-** Project should not inadvertently duplicate functionality present in other
-   OpenStack projects. If they do, they should have a clear plan and timeframe
-   to prevent long-term scope duplication.
-** Project should leverage existing functionality in other OpenStack projects
-   as much as possible
-
-* Maturity
-** Project should have an active team of contributors
-** Project should not have a major architectural rewrite planned
-
-* Process
-** Project must be hosted under stackforge (and therefore use git as its VCS)
-** Project must obey OpenStack coordinated project interface (such as tox,
-   pbr, global-requirements...)
-** Project should use oslo libraries or oslo-incubator where appropriate
-** If project is not part of an existing program, it needs to file for a new
-   program concurrently with the Incubation request, and fill the corresponding
-   requirements.
-** Project must have a well-defined core review team, with reviews distributed
-   amongst the team (and not being primarily done by one person)
-** Reviews should follow the same criteria as OpenStack projects (2 +2s
-   before +A)
-** Project should use the official openstack lists for discussion
-
-* API
-** Project APIs should be reasonably stable
-** Project must have a REST API with at least a JSON entity representation
-** Project must have a Python client library API for its REST API
-
-* QA
-** Project must have a basic devstack-gate job set up
-
-* Documentation / User support
-** Project must have docs for developers who want to contribute to the project
-** Project should have API documentation for devs who want to add to the API,
-   updated when the code is updated
-
-* Legal requirements
-** Project must be licensed under the Apache License v2
-** Project must have no library dependencies which effectively restrict how
-   the project may be distributed or deployed [1]
-** All contributors to the project must have signed the CLA
-** Project must have no known trademark issues [2]
-
-[1] https://wiki.openstack.org/wiki/LegalIssuesFAQ#Licensing_of_library_dependencies
-[2] https://wiki.openstack.org/wiki/LegalIssuesFAQ#New_Project_Names
-
-
-= Graduation to integrated =
-
-At the end of every cycle, incubated projects go through a graduation review
-to check if they are ready to be made an integral part of the next development
-cycle and be included in the next OpenStack integrated release. The TC will
-evaluate the technical maturity of the project and check a number of
-requirements, including (but not limited to):
-
-* Scope
-** Project must not duplicate functionality present in other OpenStack projects,
-   unless the project has intentionally done so with the intent of replacing it.
-** In the case that a project has intentionally duplicated functionality of
-   another project, or portion of a project, the new project must reach a level
-   of functionality and maturity such that we are ready to deprecate the old
-   code and remove it after a well defined deprecation cycle.  The deprecation
-   plan agreed to by the PTLs of each affected project, including details for
-   how users will be able to migrate from the old to the new, must be submitted
-   to the TC for review as a part of the graduation review.
-
-* Maturity
-** Project must have a large and diverse team of contributors
-** Project must have completed integration work with other integrated
-   projects, as communicated by the TC when accepted into incubation (that
-   includes Dashboard integration if applicable)
-
-* Process
-** Project must have a diverse core reviewers team (more than 4 people)
-** Core reviewers must enforce a minimum of 2 +2s before accepting a change
-** Project should have engaged with marketing team to check suitable official
-   name
-** Project must use OpenStack task, defect and design tracker(s)
-
-* QA
-** Project must have a devstack-gate job running. This gate job should install
-   the project using devstack and then run tempest tests.   This job should run
-   and vote in the check and gate pipelines for the project.  It is *not* required
-   that this job is running for the projects it depends on.  This demonstrates
-   that it would be easy to add the project to the integrated gate after
-   graduation.
-** Project must have decent unit test and functional tests coverage
-** Project must be compatible with all currently OpenStack-supported versions
-   of Python
-** Project should have a decent record of triaging incoming bugs
-
-* Documentation / User support
-** Project must have end-user docs such as API use, CLI use, Dashboard use
-** Project should have installation docs providing install/deployment in an
-   integrated manner similar to other OpenStack projects, including
-   configuration reference information for all options
-** Project should have a proven history of providing user support (on the
-   openstack@ mailing list and on Ask OpenStack)
-
-* Release management / Security
-** Project must have followed at least two common milestones (follow the common
-   cycle at least since X-2)
-** Project must have had at least one of their milestones handled by the
-   release management team (at least the X-3 milestone)
-** Project must provide a 2+ person team that will handle the project specific
-   vulnerability process [3]
-
-[3] https://wiki.openstack.org/wiki/Vulnerability_Management
-
-
-= First Integrated Cycle Expectations =
-
-In the release cycle after the project has graduated, the TC expects the project
-to reach a level of maturity for its first integrated release. In order for the
-project to graduate, the TC will need to be confident that the project will
-reach that level of maturity in the time allowed.
-
-* API
-** The REST API must be declared stable and the project must commit to
-   maintaining backwards compatibility
-** If the project has resources which would make sense to provision
-   via a Heat template, then the project should have Heat integration
-   which enables this
-** If the project has functionality which would make sense to be
-   available in the Horizon dashboard, then the project should ensure
-   that integration exists
-
-* QA
-** The project should prepare upgrade testing (currently grenade) during
-   the first integrated cycle so that it is ready to enable upgrade testing
-   jobs shortly after its first integrated release.

reference/incubation-integration-requirements.rst

@@ -0,0 +1,180 @@
+===========================================================
+ Minimal Requirements for Incubation and Integrated Status
+===========================================================
+
+Incubation
+==========
+
+The TC will evaluate the project scope and its complementarity with existing
+integrated projects and other official programs, look into the project
+technical choices, and check a number of requirements, including (but not
+limited to):
+
+Scope
+-----
+
+* Project must have a clear and defined scope.
+* Project's scope should represent a measured progression for OpenStack as a
+  whole.
+* Project should not inadvertently duplicate functionality present in other
+  OpenStack projects. If they do, they should have a clear plan and timeframe
+  to prevent long-term scope duplication.
+* Project should leverage existing functionality in other OpenStack projects
+  as much as possible
+
+Maturity
+--------
+
+* Project should have an active team of contributors
+* Project should not have a major architectural rewrite planned
+
+Process
+-------
+
+* Project must be hosted under stackforge (and therefore use git as its VCS)
+* Project must obey OpenStack coordinated project interface (such as tox,
+  pbr, global-requirements...)
+* Project should use oslo libraries or oslo-incubator where appropriate
+* If project is not part of an existing program, it needs to file for a new
+  program concurrently with the Incubation request, and fill the corresponding
+  requirements.
+* Project must have a well-defined core review team, with reviews distributed
+  amongst the team (and not being primarily done by one person)
+* Reviews should follow the same criteria as OpenStack projects (2 +2s
+  before +A)
+* Project should use the official openstack lists for discussion
+
+API
+---
+
+* Project APIs should be reasonably stable
+* Project must have a REST API with at least a JSON entity representation
+* Project must have a Python client library API for its REST API
+
+QA
+--
+
+* Project must have a basic devstack-gate job set up
+
+Documentation / User support
+----------------------------
+
+* Project must have docs for developers who want to contribute to the project
+* Project should have API documentation for devs who want to add to the API,
+  updated when the code is updated
+
+Legal requirements
+------------------
+
+* Project must be licensed under the Apache License v2
+* Project must have no library dependencies which effectively restrict how
+  the project may be distributed or deployed [1]_
+* All contributors to the project must have signed the CLA
+* Project must have no known trademark issues [2]_
+
+.. [1] https://wiki.openstack.org/wiki/LegalIssuesFAQ#Licensing_of_library_dependencies
+.. [2] https://wiki.openstack.org/wiki/LegalIssuesFAQ#New_Project_Names
+
+
+Graduation to integrated
+========================
+
+At the end of every cycle, incubated projects go through a graduation review
+to check if they are ready to be made an integral part of the next development
+cycle and be included in the next OpenStack integrated release. The TC will
+evaluate the technical maturity of the project and check a number of
+requirements, including (but not limited to):
+
+Scope
+-----
+
+* Project must not duplicate functionality present in other OpenStack projects,
+  unless the project has intentionally done so with the intent of replacing it.
+* In the case that a project has intentionally duplicated functionality of
+  another project, or portion of a project, the new project must reach a level
+  of functionality and maturity such that we are ready to deprecate the old
+  code and remove it after a well defined deprecation cycle.  The deprecation
+  plan agreed to by the PTLs of each affected project, including details for
+  how users will be able to migrate from the old to the new, must be submitted
+  to the TC for review as a part of the graduation review.
+
+Maturity
+--------
+
+* Project must have a large and diverse team of contributors
+* Project must have completed integration work with other integrated
+  projects, as communicated by the TC when accepted into incubation (that
+  includes Dashboard integration if applicable)
+
+Process
+-------
+
+* Project must have a diverse core reviewers team (more than 4 people)
+* Core reviewers must enforce a minimum of 2 +2s before accepting a change
+* Project should have engaged with marketing team to check suitable official
+  name
+* Project must use OpenStack task, defect and design tracker(s)
+
+QA
+--
+
+* Project must have a devstack-gate job running. This gate job should install
+  the project using devstack and then run tempest tests.  This job should run
+  and vote in the check and gate pipelines for the project.  It is*not* required
+  that this job is running for the projects it depends on.  This demonstrates
+  that it would be easy to add the project to the integrated gate after
+  graduation.
+* Project must have decent unit test and functional tests coverage
+* Project must be compatible with all currently OpenStack-supported versions
+  of Python
+* Project should have a decent record of triaging incoming bugs
+
+Documentation / User support
+----------------------------
+
+* Project must have end-user docs such as API use, CLI use, Dashboard use
+* Project should have installation docs providing install/deployment in an
+  integrated manner similar to other OpenStack projects, including
+  configuration reference information for all options
+* Project should have a proven history of providing user support (on the
+  openstack@ mailing list and on Ask OpenStack)
+
+Release management / Security
+-----------------------------
+
+* Project must have followed at least two common milestones (follow the common
+  cycle at least since X-2)
+* Project must have had at least one of their milestones handled by the
+  release management team (at least the X-3 milestone)
+* Project must provide a 2+ person team that will handle the project specific
+  vulnerability process [3]_
+
+.. [3] https://wiki.openstack.org/wiki/Vulnerability_Management
+
+
+First Integrated Cycle Expectations
+===================================
+
+In the release cycle after the project has graduated, the TC expects the project
+to reach a level of maturity for its first integrated release. In order for the
+project to graduate, the TC will need to be confident that the project will
+reach that level of maturity in the time allowed.
+
+API
+---
+
+* The REST API must be declared stable and the project must commit to
+  maintaining backwards compatibility
+* If the project has resources which would make sense to provision
+  via a Heat template, then the project should have Heat integration
+  which enables this
+* If the project has functionality which would make sense to be
+  available in the Horizon dashboard, then the project should ensure
+  that integration exists
+
+QA
+--
+
+* The project should prepare upgrade testing (currently grenade) during
+  the first integrated cycle so that it is ready to enable upgrade testing
+  jobs shortly after its first integrated release.

reference/index.rst

@@ -0,0 +1,14 @@
+==========================================
+ OpenStack Technical Committee References
+==========================================
+
+Reference documents which need to be revised over time.
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   charter
+   new-programs-requirements
+   incubation-integration-requirements
+

reference/new-programs-requirements.rst

@@ -1,5 +1,5 @@
 ======================================================
- Minimal requirements for new programs applications
+ Minimal Requirements for New Programs Applications
 ======================================================
 
 Teams in OpenStack can be created as-needed and grow organically. As the team

resolutions/20131106-ceilometer-and-heat-official-names.rst

@@ -1,3 +1,7 @@
+===============================================
+ 2013-31-06 Ceilometer and Heat Official Names
+===============================================
+
 The OpenStack Foundation bylaws state:
 
   https://wiki.openstack.org/wiki/Governance/Foundation/Bylaws

resolutions/20140211-tc_defcore_response.rst

@@ -1,3 +1,7 @@
+=============================
+ 2014-02-11 DefCore Response
+=============================
+
 This resolution is the draft of an email from the TC to the Board DefCore
 committee on the issue of identifying "required sections" of code.
 
@@ -122,4 +126,4 @@ requirements for future releases.
 
 3: http://lists.openstack.org/pipermail/openstack-dev/2014-February/026413.html
 
-4: http://lists.openstack.org/pipermail/openstack-dev/2014-February/026559.html
+4: http://lists.openstack.org/pipermail/openstack-dev/2014-February/026559.html

resolutions/20140402-defcore-designated-sections-guidelines.rst

@@ -1,12 +1,18 @@
+===================================================
+ 2014-04-02 DefCore Designated Sections Guidelines
+===================================================
+
 This resolution is about formally approving the general selection principles
 for "designated sections" of code, as part of the DefCore effort.
 
 Sections of code should generally be DESIGNATED when:
+
 - code provides the project external REST API, or
 - code is shared and provides common functionality for all options, or
 - code implements logic that is critical for cross-platform operation
 
 Sections of code should generally NOT be DESIGNATED when:
+
 - code interfaces to vendor-specific functions, or
 - project design explicitly intended this section to be replaceable, or
 - code extends the project external REST API in a new or different way, or

resolutions/index.rst

@@ -0,0 +1,24 @@
+=============
+ Resolutions
+=============
+
+When a motion does not result in a change in a reference doc, it can
+be expressed as a resolution.
+
+2014
+====
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   2014*
+
+2013
+====
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   2013*