Updated build & project-specific Install

Added some extra info to the build page, and the new
project-specific Install Guide section.

Change-Id: I2fdfdeb46867843209bdc43fb8725df8e652bf0b

doc/contributor-guide/source/docs-builds.rst

@@ -10,7 +10,8 @@ Documentation source and target locations
 Most documents are continuously published, they are published only from the
 master branch and there is no specific version for a stable release,
 instead they document the releases that the OpenStack community
-currently maintains. There are also version dependent documents.
+currently maintains. There are three version dependent documents: the
+Installation Guide, the Networking Guide, and the Configuration Reference.
 
 In addition to this page, the `release`_ and master branches of the
 openstack-manuals and other repositories indicate where docs are
@@ -20,10 +21,12 @@ master branch, doc source files are published for versioned documents to
 docs.openstack.org/draft and for continuously published documents to
 docs.openstack.org/ by our lovely Jenkins butlers always at the ready.
 
-Some content is completely generated using openstack-doc-tools, such as the
+Some content is generated using openstack-doc-tools, such as the
-configuration option tables and the CLI reference information. You will see
+configuration option tables and the CLI reference information. Files that are
-this warning in the source file: *<!-- This file is automatically generated,
+automatically generated have this warning at the top of the source file:
-do not edit -->*.
+*<!-- This file is automatically generated, do not edit -->*. To edit these
+files, you will need to change the content in the source files, which are
+usually in the projects' own repository.
 
 Refer to the `OpenStack Doc Tools`_ for more information on the collection
 of documentation tools used for content, such as the `auto-generation of
@@ -33,7 +36,7 @@ Installation guides
 -------------------
 
 These guides are versioned and only built from the release branches
-(stable/release_name) like the example above of stable/mitaka.
+(stable/release_name):
 
 .. list-table::
    :header-rows: 1

doc/contributor-guide/source/project-install-guide.rst

@@ -2,44 +2,55 @@
 Project specific install guides
 ===============================
 
+For the Newton release, a new method of publishing Installation Guides is
+being implemented. This will allow each big tent project to create their
+own Installation Guide, based on a standard 'cookie cutter' template, in
+their own repository. These guides are then centrally published to the
+docs.openstack.org page.
+
+For updates on the progress of this project, see the ``Install Guide wiki
+page <https://wiki.openstack.org/wiki/Documentation/InstallGuideWorkItems>``.
+If you would like to help out, ``attend a meeting
+<http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting>``.
+
 Project specific installation guides can be set up as follows:
 
-* Use the ``installguide-cookiecutter
+#. Use the ``installguide-cookiecutter
-  <https://git.openstack.org/cgit/openstack/installguide-cookiecutter>``
+   <https://git.openstack.org/cgit/openstack/installguide-cookiecutter>``
-  cookiecutter to create a skeleton for your project.
+   to create a skeleton for your project.
 
-  This adds content to the ``install-guide`` directory in the
+   This adds content to the ``install-guide`` directory in the
-  top-level of the project repository.
+   top-level of the project repository.
 
-* Include a ``tox.ini`` environment for 'install-guide':
+#. Include a ``tox.ini`` environment for 'install-guide':
 
-  .. code::
+   .. code::
 
-     [testenv:install-guide]
+      [testenv:install-guide]
-     # NOTE(jaegerandi): this target does not use constraints because
+      # NOTE(jaegerandi): this target does not use constraints because
-     # upstream infra does not yet support it. Once that's fixed, we can
+      # upstream infra does not yet support it. Once that's fixed, we can
-     # drop the install_command.
+      # drop the install_command.
-     install_command = pip install -U --force-reinstall {opts} {packages}
+      install_command = pip install -U --force-reinstall {opts} {packages}
-     commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html
+      commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html
 
-* Add the python package ``openstackdocs-theme``  to the
+#. Add the python package ``openstackdocs-theme``  to the
-  ``test-requirements.txt`` file.
+   ``test-requirements.txt`` file.
 
-* Once the changes above are merged, add jobs for it in the
+#. Once the changes above are merged, add jobs for it in the
-  ``openstack-infra/project-config`` repository. Define the jobs using
+   ``openstack-infra/project-config`` repository. Define the jobs using
-  the JJB ``install-guide-jobs`` job-template in file
+   the JJB ``install-guide-jobs`` job-template in file
-  ``jenkins/jobs/projects.yaml`` like:
+   ``jenkins/jobs/projects.yaml`` like:
 
-  .. code-block:: yaml
+   .. code-block:: yaml
 
-     ...
+      ...
-     - install-guide-jobs:
+      - install-guide-jobs:
          service: orchestration
 
-  Here ``service`` is the service name of the project, like
+   Here ``service`` is the service name of the project, like
-  orchestration for heat.
+   orchestration for heat.
 
-  Add the ``install-guide-jobs`` template to ``zuul/layout.yaml`` to
+#. Add the ``install-guide-jobs`` template to ``zuul/layout.yaml`` to
-  schedule the jobs.
+   schedule the jobs.
 
-* TBD: How to create master index file for this.
+TBD: How to create master index file for this.