openstack/openstack-manuals
Code Issues Proposed changes

Merge "update contributor guide based on changes after migration project"

Browse Source
This commit is contained in:
Jenkins 2017-07-03 15:54:41 +00:00 committed by Gerrit Code Review
commit 14967e5ec3
7 changed files with 109 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/contributor-guide/source/blueprints-and-specs.rst
View File

@ -42,14 +42,21 @@ For more information, see :ref:`doc_bugs`.
Release-specific documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Installation Tutorials and 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.
Release-specific documentation is published continuously as changes are
made, with different versions for each series. The following guides
are release specific:
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.
* Configuration reference
* Command-line reference
* Installation tutorials and guides
* Networking guide
To patch release-specific documentation, you should
patch the master branch with "backport: xxxx" (for example, backport:
kilo) in the commit message. During Pike, much of the material
maintained by the documentation team was moved into project team
repositories, so patching the same content for different release
series may mean looking for the relevant files in multiple places.
For these guides, the docs.openstack.org site defaults to the current release,
with the previous two releases being available under the ``More Releases
@ -66,8 +73,14 @@ remove them entirely.
Installation Tutorials and Guides
---------------------------------
The OpenStack Installation Tutorials and Guides describe a manual install
process for multiple distributions based on the following packaging systems:
Starting with Pike, the OpenStack Installation Tutorials and Guides
are maintained by the project teams, with assistance from the
documentation team. The guides describe a manual install process for
multiple distributions based on openSUSE and SUSE Linux Enterprise
Server; Red Hat Enterprise Linux and CentOS; and Ubuntu 16.04 (LTS).
Prior to Pike, the documentation team maintained OpenStack
Installation Tutorials and Guides:
.. list-table::
:header-rows: 1
@ -99,6 +112,11 @@ process for multiple distributions based on the following packaging systems:
Guides for deployers and administrators
---------------------------------------
Starting with Pike, configuration reference and administrator guides
are maintained by each project team.
Prior to Pike, the documentation team maintained combined guides:
* `OpenStack Configuration Reference
<https://docs.openstack.org/ocata/config-reference/>`_:
Contains a reference listing of all configuration options for OpenStack
@ -235,21 +253,18 @@ project repositories and we will have redirects in place for these API pages.
Project-specific guides
-----------------------
Each project maintains its own developer guide.
They are published from each project repository.
See https://docs.openstack.org/developer/openstack-projects.html
and https://docs.openstack.org/developer/language-bindings.html.
Each project maintains its own guides for installation,
administration, configuration reference, and contributors. They are
published from each project repository. See
https://docs.openstack.org/openstack-projects.html and
https://docs.openstack.org/language-bindings.html.
Contributor guides
------------------
Generally, the https://docs.openstack.org/developer/ documentation is meant
for contributors to OpenStack projects. Each project's repo has a
``doc/source`` directory where RST source files are stored. They are built
automatically with Sphinx when the patch is merged. For example, see
https://git.openstack.org/cgit/openstack/horizon/tree/doc/source for the
horizon contributor documentation source and https://docs.openstack.org/developer/horizon/
for the built documentation.
Each project's repo has a ``doc/source`` directory where RST source
files are stored. They are built automatically with Sphinx when the
patch is merged. For example, see
https://git.openstack.org/cgit/openstack/horizon/tree/doc/source for
the horizon documentation source and
https://docs.openstack.org/horizon/ for the built documentation.
* `Infrastructure User Manual <https://docs.openstack.org/infra/manual>`_:
Reference documentation for tools and processes used for all
@ -273,12 +288,12 @@ for the built documentation.
* - Python Developer Documentation
- https://git.openstack.org/cgit/openstack/<project>/tree/master/doc/source/,
such as https://git.openstack.org/cgit/openstack/nova/tree/doc/source
- https://docs.openstack.org/developer/openstack-projects.html
- https://docs.openstack.org/openstack-projects.html
* - Language Bindings and Python Clients
- https://git.openstack.org/cgit/openstack/python-<project>client/tree/master/doc/source/,
such as https://git.openstack.org/cgit/openstack/python-novaclient/tree/doc/source
- https://docs.openstack.org/developer/language-bindings.html
- https://docs.openstack.org/language-bindings.html
* - OpenStack Project Infrastructure
- https://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source
@ -286,7 +301,7 @@ for the built documentation.
* - Tempest Testing Project
- https://git.openstack.org/cgit/openstack/tempest/tree/doc/source
- https://docs.openstack.org/developer/tempest/
- https://docs.openstack.org/tempest/latest/
Guides for contributors
-----------------------

6
doc/contributor-guide/source/doc-tools/cli-reference.rst
View File

@ -2,6 +2,12 @@
Generate Command-Line Interface Reference
=========================================
.. note::
These instructions apply to the guides produced prior to the Pike
release. The command line reference guides are now managed in the
project repositories.
The OpenStack Command-Line Interface (CLI) Reference source files are stored
in the ``openstack-manuals`` repository. The majority of files are
automatically generated and should not be modified manually. To update

8
doc/contributor-guide/source/doc-tools/config-reference.rst
View File

@ -2,6 +2,14 @@
Generate Configuration Reference
================================
.. note::
These instructions apply to the guides produced prior to the Pike
release. The configuration reference guides are now managed in the
project repositories using `the Sphinx integration provided by
oslo.config
<https://docs.openstack.org/developer/oslo.config/sphinxext.html>`__.
The OpenStack Configuration Reference source files are stored
in the ``openstack-manuals`` repository. The majority of files are
automatically generated and should not be modified manually. To update

8
doc/contributor-guide/source/doc-tools/scripts.rst
View File

@ -49,7 +49,13 @@ Several scripts currently reside in the `openstack-manuals
beneficial to consolidate these into the ``openstack-doc-tools`` repository.
www-generator.py
Generates static, template-based HTML files for https://docs.openstack.org/.
Generates static, template-based HTML files for
https://docs.openstack.org/. The script reads YAML data files in
``www/project-data`` to determine which projects exist in a given
series and how they should be displayed on the list of installation,
configuration, and other guides. The file
``www/project-data/schema.yaml`` contains the JSONSchema settings to
describe what a valid data file looks like.
sync-projects.sh
Synchronizes the **Glossary**, common files, and some translations

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

@ -1,13 +1,37 @@
.. _project-install-guide:
=================================
Installation tutorials and guides
=================================
Pike and later
~~~~~~~~~~~~~~
Each official OpenStack project should maintain an installation guide
following the layout described in the `documentation migration
spec`_. When the guide is available, update
``openstack-manuals/www/project-data/latest.yaml`` to include
information about the project and ensure that the
``has_install_guide`` flag is set to ``true`` to ensure that the guide
is listed along with the guides from other projects.
.. _documentation migration spec: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
Newton and Ocata
~~~~~~~~~~~~~~~~
For the Newton release, a new method of publishing installation tutorials
and guides is being implemented. This will allow each big tent project to
create their own installation guide, based on a standard template,
in their own repository. These guides are then centrally published to
`docs.openstack.org <https://docs.openstack.org>`_.
.. warning::
These instructions are superseded by the `documentation migration
spec`_. New installation guides should be created using the layout
defined in the spec, rather than the following instructions.
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

14
doc/contributor-guide/source/quickstart/new-projects.rst
View File

@ -8,12 +8,12 @@ If you are maintaining a new project that has recently been accepted into the
OpenStack 'big tent' then you will require some documentation for your
project.
Developer documentation for your project should live in your project's git
repository, and be published to `docs.openstack.org/developer/yourproject`.
If you need to create that index page, send a patch to the openstack-manuals
team. You will also need to add the ``openstack-server-publish`` job to the
appropriate repositories so that the index page is re-published with every
commit.
Documentation for your project should live in your project's
git repository, and be published to `docs.openstack.org/yourproject`.
If you need to create that index page, you will also need to add the
``openstack-unified-publish-jobs`` to the appropriate repositories by
updating the settings in the ``project-config`` repository so that the
documentation is re-published with every commit.
Any configuration options or command line tools should be documented using
the automated ``openstack-doc-tools``. For more information about these
@ -21,4 +21,4 @@ automated tools, see the :ref:`doc-tools` chapter.
To create an Installation Tutorial in accordance with the OpenStack
Foundation Project Navigator, follow the instructions at
``project-install-guide``.
:ref:`project-install-guide`.

29
doc/contributor-guide/source/release/taskdetail.rst
View File

@ -72,13 +72,23 @@ Make the following changes in the **openstack-manuals** repository:
- ``/www/RELEASE/index.html``
#. Create the project-install-guide index pages for the new release, using the
existing pages as templates:
#. Copy the latest project data file to one named for the release:
.. code-block:: console
$ cp www/project-data/latest.yaml www/project-data/RELEASE.yaml
#. Create the project-install-guide index page for the new release, using the
existing page as a template:
- ``/www/project-install-guide/RELEASE/index.html``
- ``/www/project-install-guide/RELEASE/obs-services.html``
- ``/www/project-install-guide/RELEASE/rdo-services.html``
- ``/www/project-install-guide/RELEASE/ubuntu-services.html``
#. Modify the new file to set the ``SERIES`` variable for the template
correctly:
.. code-block:: jinja
{% set SERIES = "RELEASE" %}
#. Create the ``project-deploy-guide`` index for the new release, using the
existing page as a template:
@ -98,7 +108,7 @@ Make the following changes in the **openstack-manuals** repository:
#. Update the site redirects. Merge this patch on release day:
- ``/www/static/.htaccess``
- ``/www/.htaccess``
#. Update the *Get started* links. Do not merge this patch until after the
links are active:
@ -121,13 +131,6 @@ additional services Installation Guides in
``doc/install-guide/source/additional-services.rst``. Update these links to
the correct version before publishing the book.
Run scripts for Configuration and CLI Reference Guides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run scripts to pull the latest changes for the Configuration Reference and
CLI Reference Guides. Instructions for using these scripts are in the
:ref:`doc-tools` chapter.
Update main docs page
~~~~~~~~~~~~~~~~~~~~~