openstack
/
openstack-manuals
Code Issues Proposed changes

Updated build & project-specific Install 

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

Change-Id: I2fdfdeb46867843209bdc43fb8725df8e652bf0b
This commit is contained in:
Lana Brindley 2016-06-14 12:56:53 +10:00 committed by KATO Tomoyuki
parent 16c1e98760
commit 3946ab13c2
2 changed files with 47 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/contributor-guide/source/docs-builds.rst
View File

@ -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
configuration option tables and the CLI reference information. You will see
this warning in the source file: *<!-- This file is automatically generated,
do not edit -->*.
Some content is generated using openstack-doc-tools, such as the
configuration option tables and the CLI reference information. Files that are
automatically generated have this warning at the top of the source file:
*<!-- 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

65
doc/contributor-guide/source/project-install-guide.rst
View File

@ -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
<https://git.openstack.org/cgit/openstack/installguide-cookiecutter>``
cookiecutter to create a skeleton for your project.
#. Use the ``installguide-cookiecutter
<https://git.openstack.org/cgit/openstack/installguide-cookiecutter>``
to create a skeleton for your project.
This adds content to the ``install-guide`` directory in the
top-level of the project repository.
This adds content to the ``install-guide`` directory in the
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]
# NOTE(jaegerandi): this target does not use constraints because
# upstream infra does not yet support it. Once that's fixed, we can
# drop the install_command.
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
[testenv:install-guide]
# NOTE(jaegerandi): this target does not use constraints because
# upstream infra does not yet support it. Once that's fixed, we can
# drop the install_command.
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
* Add the python package ``openstackdocs-theme`` to the
``test-requirements.txt`` file.
#. Add the python package ``openstackdocs-theme`` to the
``test-requirements.txt`` file.
* Once the changes above are merged, add jobs for it in the
``openstack-infra/project-config`` repository. Define the jobs using
the JJB ``install-guide-jobs`` job-template in file
``jenkins/jobs/projects.yaml`` like:
#. Once the changes above are merged, add jobs for it in the
``openstack-infra/project-config`` repository. Define the jobs using
the JJB ``install-guide-jobs`` job-template in file
``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
orchestration for heat.
Here ``service`` is the service name of the project, like
orchestration for heat.
Add the ``install-guide-jobs`` template to ``zuul/layout.yaml`` to
schedule the jobs.
#. Add the ``install-guide-jobs`` template to ``zuul/layout.yaml`` to
schedule the jobs.
* TBD: How to create master index file for this.
TBD: How to create master index file for this.