[doc-contrib-guide] Update release and install/deploy docs
Remove outdated or unneeded information, particularly guide lists. Change-Id: I53cc71a9645a28e34b78aefea0ec53ae7db6520d
This commit is contained in:
parent
adcc14cd0b
commit
c6a983fdc1
@ -1,36 +1,32 @@
|
|||||||
.. _content-specs:
|
.. _content-specs:
|
||||||
|
|
||||||
=====================
|
=============================
|
||||||
Content specification
|
|
||||||
=====================
|
|
||||||
|
|
||||||
Blueprints and specifications
|
Blueprints and specifications
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
=============================
|
||||||
|
|
||||||
The Documentation team uses specifications in the `docs-specs repository
|
The Documentation team uses specifications in the `docs-specs repository
|
||||||
<https://git.openstack.org/cgit/openstack/docs-specs>`_ to maintain large
|
<https://git.openstack.org/cgit/openstack/docs-specs>`_ to maintain large
|
||||||
changes. Approved specifications are published at `Documentation Program
|
changes. Approved specifications are published at `Documentation Program
|
||||||
Specifications <https://specs.openstack.org/openstack/docs-specs>`_.
|
Specifications <https://specs.openstack.org/openstack/docs-specs>`_.
|
||||||
For tracking purposes, a blueprint is created for each specification. It is
|
For tracking purposes, a blueprint is created for each specification.
|
||||||
also good practice to contact the project team or subteam for the book you want
|
|
||||||
to change to discuss your changes before starting work.
|
|
||||||
|
|
||||||
Use blueprints and specifications:
|
Use blueprints and specifications:
|
||||||
|
|
||||||
|
* For any large reorganization of a deliverable or set of deliverables.
|
||||||
|
* For infrastructure or automation work that needs to be designed prior to
|
||||||
|
proposing a patch.
|
||||||
|
* When adding an entirely new deliverable to the docs project.
|
||||||
* When adding large sections to an existing document to ensure involvement
|
* When adding large sections to an existing document to ensure involvement
|
||||||
of the docs core team.
|
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
|
* For any work that requires both content and tooling changes, such as
|
||||||
addition of the API reference site.
|
addition of the API reference site.
|
||||||
* For any large reorganization of a deliverable or set of deliverables.
|
* For work that should definitely be discussed at a project teams gathering.
|
||||||
* 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.
|
A specification needs two +2 votes from the docs-specs-core team.
|
||||||
See the current list of `docs-specs core team
|
See the current list of `docs-specs core team
|
||||||
<https://review.openstack.org/#/admin/groups/384,members>`_.
|
<https://review.openstack.org/#/admin/groups/384,members>`_.
|
||||||
|
|
||||||
Use bugs against openstack-manuals or openstack-api-site:
|
Use bugs against a particular repository with documentation:
|
||||||
|
|
||||||
* For known content issues, even if you have to do multiple patches to close
|
* For known content issues, even if you have to do multiple patches to close
|
||||||
the bug.
|
the bug.
|
||||||
@ -38,305 +34,3 @@ Use bugs against openstack-manuals or openstack-api-site:
|
|||||||
* For known errors in a document.
|
* For known errors in a document.
|
||||||
|
|
||||||
For more information, see :ref:`doc_bugs`.
|
For more information, see :ref:`doc_bugs`.
|
||||||
|
|
||||||
Release-specific documentation
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Release-specific documentation is published continuously as changes are
|
|
||||||
made, with different versions for each series.
|
|
||||||
|
|
||||||
To patch release-specific documentation, submit your
|
|
||||||
patch to 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.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The following guides were release specific before the Pike
|
|
||||||
migration:
|
|
||||||
|
|
||||||
* Configuration reference
|
|
||||||
* Command-line reference
|
|
||||||
* Installation guides
|
|
||||||
* Networking guide
|
|
||||||
|
|
||||||
For these guides, the docs.openstack.org site defaults to the current release,
|
|
||||||
with the previous two releases being available under the ``More Releases
|
|
||||||
& Languages`` drop-down. At release time, the documentation release team
|
|
||||||
will update the default page to the new release, and remove the link to
|
|
||||||
the oldest release. These docs are still available online for people who
|
|
||||||
have direct URLs to the content, but they are no longer linked from the
|
|
||||||
main site. For books written in DocBook XML, these old versions are clearly
|
|
||||||
marked with the release name in red down the left-hand margin. We are
|
|
||||||
currently developing a similar method of marking older books written in RST.
|
|
||||||
The core team tracks usage of older versions, and as usage falls, can
|
|
||||||
remove them entirely.
|
|
||||||
|
|
||||||
Installation Guides
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
Starting with Pike, the OpenStack Installation 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 Guides:
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Document
|
|
||||||
- Source location
|
|
||||||
- Target location
|
|
||||||
|
|
||||||
* - Installation Guide for openSUSE and SUSE Linux Enterprise Server
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
|
|
||||||
- https://docs.openstack.org/ocata/install-guide-obs/
|
|
||||||
|
|
||||||
* - Installation Guide for Red Hat Enterprise Linux and CentOS
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
|
|
||||||
- https://docs.openstack.org/ocata/install-guide-rdo/
|
|
||||||
|
|
||||||
* - Installation Guide for Ubuntu 16.04 (LTS)
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
|
|
||||||
- https://docs.openstack.org/ocata/install-guide-ubuntu/
|
|
||||||
|
|
||||||
* - Installation Guide For Debian With Debconf (is not provided for Ocata)
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
|
|
||||||
- https://docs.openstack.org/newton/install-guide-debconf/
|
|
||||||
|
|
||||||
* - Installation Guide For Debian (is not provided for Ocata)
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
|
|
||||||
- https://docs.openstack.org/newton/install-guide-debian/
|
|
||||||
|
|
||||||
Guides for deployers and administrators
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
As of Pike, the configuration reference and administration guide(s)
|
|
||||||
are maintained by each project team.
|
|
||||||
|
|
||||||
Prior to Pike, the documentation team maintained the following
|
|
||||||
combined guides:
|
|
||||||
|
|
||||||
* `OpenStack Configuration Reference
|
|
||||||
<https://docs.openstack.org/ocata/config-reference/>`_:
|
|
||||||
Contains a reference listing of all configuration options for OpenStack
|
|
||||||
services by release version.
|
|
||||||
* `OpenStack Networking Guide
|
|
||||||
<https://docs.openstack.org/ocata/networking-guide/>`_:
|
|
||||||
This guide targets OpenStack administrators seeking to deploy and manage
|
|
||||||
OpenStack Networking (neutron).
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Document
|
|
||||||
- Source location
|
|
||||||
- Target location
|
|
||||||
|
|
||||||
* - Configuration Reference
|
|
||||||
- Maintained in project specific repositories
|
|
||||||
- https://docs.openstack.org/ocata/config-reference/
|
|
||||||
|
|
||||||
* - OpenStack Networking Guide
|
|
||||||
- https://github.com/openstack/neutron/tree/master/doc/source/admin
|
|
||||||
- https://docs.openstack.org/ocata/networking-guide/
|
|
||||||
|
|
||||||
Continuously released documentation
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
These guides cover multiple versions and follows the general
|
|
||||||
`release information <https://wiki.openstack.org/wiki/Releases>`_.
|
|
||||||
The guides cover the latest two versions, for
|
|
||||||
example Juno and Kilo. The following exceptions apply:
|
|
||||||
|
|
||||||
* HA Guide: Updated last at Havana timeframe, still needs updates
|
|
||||||
|
|
||||||
Guides for deployers and administrators
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Document
|
|
||||||
- Source location
|
|
||||||
- Target location
|
|
||||||
|
|
||||||
* - OpenStack Architecture Design Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/arch-design
|
|
||||||
- https://docs.openstack.org/arch-design/
|
|
||||||
|
|
||||||
* - OpenStack Administrator Guide
|
|
||||||
- Maintained in project specific repositories
|
|
||||||
- https://docs.openstack.org/admin-guide/
|
|
||||||
|
|
||||||
* - OpenStack High Availability Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/ha-guide
|
|
||||||
- https://docs.openstack.org/ha-guide/
|
|
||||||
|
|
||||||
* - OpenStack Security Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/security-doc/tree/security-guide
|
|
||||||
- https://docs.openstack.org/security-guide/
|
|
||||||
|
|
||||||
* - OpenStack Virtual Machine Image Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/image-guide
|
|
||||||
- https://docs.openstack.org/image-guide/
|
|
||||||
|
|
||||||
Guides for end users
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
* `OpenStack API Guide
|
|
||||||
<https://developer.openstack.org/api-guide/quick-start/>`_:
|
|
||||||
A brief overview of how to send REST API requests to endpoints for
|
|
||||||
OpenStack services.
|
|
||||||
* `OpenStack Command-Line Interface Reference
|
|
||||||
<https://docs.openstack.org/cli-reference/>`_:
|
|
||||||
Automatically generates help text for CLI commands and subcommands.
|
|
||||||
* `OpenStack End User Guide
|
|
||||||
<https://docs.openstack.org/user/>`_:
|
|
||||||
This guide contains project-specific documentation for using OpenStack
|
|
||||||
services and libraries.
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Document
|
|
||||||
- Source location
|
|
||||||
- Target location
|
|
||||||
|
|
||||||
* - OpenStack API Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start
|
|
||||||
- https://developer.openstack.org/api-guide/quick-start/
|
|
||||||
|
|
||||||
* - OpenStack Command-Line Interface Reference
|
|
||||||
- https://git.openstack.org/cgit/openstack/oslo.config/tree/doc/source/cli
|
|
||||||
- https://docs.openstack.org/cli-reference/
|
|
||||||
|
|
||||||
* - OpenStack Project User Guides
|
|
||||||
- Maintained in project specific repositories
|
|
||||||
- https://docs.openstack.org/user/
|
|
||||||
|
|
||||||
API documentation
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
* `Complete API Reference <https://developer.openstack.org/api-guide/quick-start/index.html>`_:
|
|
||||||
Complete reference listing of OpenStack REST APIs
|
|
||||||
with example requests and responses.
|
|
||||||
* `API specifications <http://specs.openstack.org/>`_:
|
|
||||||
Within project's specification repos, some have opted
|
|
||||||
to document API specifications, such as Identity.
|
|
||||||
* `Object Storage API v1
|
|
||||||
<https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html>`_
|
|
||||||
|
|
||||||
Project-specific guides
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
Each project maintains its own guides for installation,
|
|
||||||
administration, configuration reference, and contributors. They are
|
|
||||||
published from each project repository. See the
|
|
||||||
`OpenStack Projects <https://docs.openstack.org/openstack-projects.html>`_ and
|
|
||||||
the `OpenStack API Bindings <https://docs.openstack.org/language-bindings.html>`_
|
|
||||||
pages for more information.
|
|
||||||
|
|
||||||
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
|
|
||||||
the ` horizon documentation source <https://git.openstack.org/cgit/openstack/horizon/tree/doc/source>`_
|
|
||||||
and the `built documentation <https://docs.openstack.org/horizon/>`_.
|
|
||||||
|
|
||||||
* `Infrastructure User Manual <https://docs.openstack.org/infra/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.
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Document
|
|
||||||
- Source location
|
|
||||||
- Target location
|
|
||||||
|
|
||||||
* - Documentation Contributor Guide
|
|
||||||
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/doc-contrib-guide
|
|
||||||
- https://docs.openstack.org/doc-contrib-guide/
|
|
||||||
|
|
||||||
* - 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/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/language-bindings.html
|
|
||||||
|
|
||||||
* - OpenStack Project Infrastructure
|
|
||||||
- https://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source
|
|
||||||
- https://docs.openstack.org/infra/system-config/
|
|
||||||
|
|
||||||
* - Tempest Testing Project
|
|
||||||
- https://git.openstack.org/cgit/openstack/tempest/tree/doc/source
|
|
||||||
- https://docs.openstack.org/tempest/latest/
|
|
||||||
|
|
||||||
Guides for contributors
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
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/<projectname>/latest): 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/<projectname>/latest): 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
|
|
||||||
|
@ -4,11 +4,12 @@ Landing pages on docs.openstack.org
|
|||||||
|
|
||||||
The main index pages on docs.openstack.org are part of the
|
The main index pages on docs.openstack.org are part of the
|
||||||
``openstack-manuals`` repository in the ``www`` folder. These are
|
``openstack-manuals`` repository in the ``www`` folder. These are
|
||||||
generated with using a :ref:`template generator <template-generator>`.
|
generated with using a template generator as described in
|
||||||
|
:doc:`doc-tools/template-generator`.
|
||||||
|
|
||||||
Official OpenStack projects hosted on the ``docs.openstack.org`` site
|
Official OpenStack projects hosted on the ``docs.openstack.org`` site
|
||||||
should add their links to the main index pages as explained at
|
should add their links to the main index pages as explained at
|
||||||
:ref:`template-generator`.
|
:doc:`doc-tools/template-generator`.
|
||||||
|
|
||||||
For projects with many subprojects, like deployment projects or
|
For projects with many subprojects, like deployment projects or
|
||||||
plug-in lists of networking or bare metal, the main project page
|
plug-in lists of networking or bare metal, the main project page
|
||||||
|
@ -12,7 +12,7 @@ Reviewing documentation
|
|||||||
OpenStack documentation is treated in the same way as code, and follows the
|
OpenStack documentation is treated in the same way as code, and follows the
|
||||||
standard code review process. To see what documentation changes are ready for
|
standard code review process. To see what documentation changes are ready for
|
||||||
review, use the `Documentation Program Dashboard
|
review, use the `Documentation Program Dashboard
|
||||||
<https://is.gd/openstackdocsreviewreloaded>`_ or the appropriate list of
|
<https://is.gd/openstackdocsdashboard>`_ or the appropriate list of
|
||||||
Gerrit reviews for repositories with documentation.
|
Gerrit reviews for repositories with documentation.
|
||||||
|
|
||||||
The Documentation Program Dashboard only lists changes to repositories that
|
The Documentation Program Dashboard only lists changes to repositories that
|
||||||
@ -46,7 +46,7 @@ Once done, follow the steps below to submit a patch review.
|
|||||||
#. If you want to review patches for the repositories managed by the
|
#. If you want to review patches for the repositories managed by the
|
||||||
Documentation project or the project's subteams, go to the
|
Documentation project or the project's subteams, go to the
|
||||||
`Documentation Program Dashboard
|
`Documentation Program Dashboard
|
||||||
<https://is.gd/openstackdocsreviewreloaded>`_.
|
<https://is.gd/openstackdocsdashboard>`_.
|
||||||
|
|
||||||
To review patches for project teams' repositories, use the list of Gerrit
|
To review patches for project teams' repositories, use the list of Gerrit
|
||||||
changes for the appropriate project.
|
changes for the appropriate project.
|
||||||
|
@ -1,14 +0,0 @@
|
|||||||
=============
|
|
||||||
Landing pages
|
|
||||||
=============
|
|
||||||
|
|
||||||
There are now central landing pages for the various project guides.
|
|
||||||
For example, there is now one central place for the Administrator Guide
|
|
||||||
at `https://docs.openstack.org/pike/admin/index.html`.
|
|
||||||
|
|
||||||
To add your project content to these guides, change the file
|
|
||||||
`www/project-data/latest.yaml
|
|
||||||
<http://git.openstack.org/cgit/openstack/openstack-manuals/tree/www/project-data/latest.yaml>`_
|
|
||||||
in the openstack-manuals repository.
|
|
||||||
|
|
||||||
See :ref:`template-generator` for details.
|
|
@ -72,12 +72,6 @@ Setting up
|
|||||||
|
|
||||||
#. Commit the changes to your project repository for review.
|
#. Commit the changes to your project repository for review.
|
||||||
|
|
||||||
To create or update the master index file, create or update the
|
|
||||||
``www/project-deploy-guide/RELEASE/index.html`` file at the
|
|
||||||
``openstack-manuals`` repository.
|
|
||||||
|
|
||||||
For draft (unreleased) version, replace ``RELEASE`` with ``draft``.
|
|
||||||
|
|
||||||
After these changes merge, you can set up the jobs for building in the
|
After these changes merge, you can set up the jobs for building in the
|
||||||
OpenStack Infra ``project-config`` repository:
|
OpenStack Infra ``project-config`` repository:
|
||||||
|
|
||||||
@ -118,6 +112,9 @@ OpenStack Infra ``project-config`` repository:
|
|||||||
|
|
||||||
#. Commit the changes to the infra repository for review.
|
#. Commit the changes to the infra repository for review.
|
||||||
|
|
||||||
|
To update the main index pages with a link to your deployment guide, see
|
||||||
|
:doc:`doc-tools/template-generator`.
|
||||||
|
|
||||||
Deployment guide and installation guide links
|
Deployment guide and installation guide links
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
@ -86,4 +86,3 @@ by the documentation team.
|
|||||||
|
|
||||||
project-install-guide.rst
|
project-install-guide.rst
|
||||||
project-deploy-guide.rst
|
project-deploy-guide.rst
|
||||||
landing-pages.rst
|
|
||||||
|
@ -8,34 +8,25 @@ Pike and later
|
|||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Each official OpenStack project should maintain an installation guide
|
Each official OpenStack project should maintain an installation guide
|
||||||
following the layout described in the `documentation migration
|
following the layout described in :doc:`project-guides`. When the guide is
|
||||||
spec`_. When the guide is available, update
|
available, update ``openstack-manuals/www/project-data/latest.yaml`` to include
|
||||||
``openstack-manuals/www/project-data/latest.yaml`` to include
|
|
||||||
information about the project and ensure that the
|
information about the project and ensure that the
|
||||||
``has_install_guide`` flag is set to ``true`` to ensure that the guide
|
``has_install_guide`` flag is set to ``true`` to ensure that the guide
|
||||||
is listed along with the guides from other projects.
|
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
|
Newton and Ocata
|
||||||
~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
For the Newton release, a new method of publishing installation
|
For the Newton and Ocata releases only, big tent projects created their own
|
||||||
guides is being implemented. This will allow each big tent project to
|
installation guides, based on a standard template, in their own repository.
|
||||||
create their own installation guide, based on a standard template,
|
These guides were then centrally published to
|
||||||
in their own repository. These guides are then centrally published to
|
|
||||||
`docs.openstack.org <https://docs.openstack.org>`_.
|
`docs.openstack.org <https://docs.openstack.org>`_.
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
These instructions are superseded by the `documentation migration
|
The following instructions are superseded by :doc:`project-guides`. New
|
||||||
spec`_. New installation guides should be created using the layout
|
installation guides should be created using the layout defined in the spec,
|
||||||
defined in the spec, rather than the following instructions.
|
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
|
|
||||||
<http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting>`_.
|
|
||||||
|
|
||||||
Set up project specific installation guides:
|
Set up project specific installation guides:
|
||||||
|
|
||||||
@ -147,8 +138,3 @@ After these changes have merged, you can set up the jobs for building.
|
|||||||
This schedules the Install Guide jobs.
|
This schedules the Install Guide jobs.
|
||||||
|
|
||||||
#. Commit the changes to the infra repository for review.
|
#. Commit the changes to the infra repository for review.
|
||||||
|
|
||||||
To create or update the master index file, create or update the
|
|
||||||
``www/RELEASE/install/index.html`` file and the
|
|
||||||
``doc/install-guide/source/additional-services.rst`` at the
|
|
||||||
``openstack-manuals`` repository.
|
|
||||||
|
@ -57,12 +57,12 @@ OpenStack Manuals no longer handles release notes for the project teams.
|
|||||||
However, we do need to write release notes for our documentation. Release
|
However, we do need to write release notes for our documentation. Release
|
||||||
notes should be added as major changes occur throughout the release, however
|
notes should be added as major changes occur throughout the release, however
|
||||||
this is often overlooked - both by authors and reviewers - and thus a final
|
this is often overlooked - both by authors and reviewers - and thus a final
|
||||||
review is needed to check that all major changes are in. Contact each
|
review is needed to check that all major changes are in. Contact each subteam
|
||||||
Specialty Team lead, listed at :doc:`../team-structure`, and ask them for
|
lead, listed at :doc:`../team-structure`, and ask them for the notes for the
|
||||||
the notes for the books they look after. The source repository for release
|
documentation they look after. The source for release notes is
|
||||||
notes is `openstack-manuals/releasenotes/source/RELEASENAME` and they are
|
``openstack-manuals/releasenotes/source/RELEASENAME.rst`` and they are
|
||||||
published to
|
published to
|
||||||
`https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html`.
|
``https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html``.
|
||||||
|
|
||||||
.. _release-www-page-updates:
|
.. _release-www-page-updates:
|
||||||
|
|
||||||
@ -161,7 +161,7 @@ Make the following changes in the **openstack-manuals** repository:
|
|||||||
pushed at release time, so be prepared to have the release day
|
pushed at release time, so be prepared to have the release day
|
||||||
patches ready well ahead of the official release time. You can
|
patches ready well ahead of the official release time. You can
|
||||||
check the current gate status at `Zuul status
|
check the current gate status at `Zuul status
|
||||||
<http://status.openstack.org/zuul/>`_ to get an idea of the current
|
<http://zuul.openstack.org/>`_ to get an idea of the current
|
||||||
merge times.
|
merge times.
|
||||||
|
|
||||||
Generate the site map
|
Generate the site map
|
||||||
@ -203,23 +203,7 @@ To:
|
|||||||
|
|
||||||
This guide documents OpenStack Newton and Mitaka releases.
|
This guide documents OpenStack Newton and Mitaka releases.
|
||||||
|
|
||||||
However, we will keep the documentation on the
|
|
||||||
`docs.openstack.org <https://docs.openstack.org/>`_
|
|
||||||
page for a while so that the users can refer the guides if necessary.
|
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
See :ref:`docs_builds_eol` for instructions for building
|
See :ref:`docs_builds_eol` for instructions for building
|
||||||
documentation for versions past their end-of-life.
|
documentation for versions past their end-of-life.
|
||||||
|
|
||||||
Removing series landing pages
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
To remove the landing pages for a series that has passed its end of
|
|
||||||
life date, delete the series directory under ``www`` and remove the
|
|
||||||
associated project data file.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ git rm -r www/SERIES
|
|
||||||
$ git rm www/project-data/SERIES.yaml
|
|
||||||
|
@ -10,24 +10,17 @@ Release day is usually 1300UTC on the `initial release date` listed on the
|
|||||||
|
|
||||||
*Four to six weeks before release*
|
*Four to six weeks before release*
|
||||||
Ping packagers to locate pre-release packages to test the Installation
|
Ping packagers to locate pre-release packages to test the Installation
|
||||||
Guide against, and start looking for willing volunteers to help test.
|
Guides against, and start looking for willing volunteers to help test.
|
||||||
|
|
||||||
*Four weeks*
|
|
||||||
Ping Cross Project Liaisons (CPLs) to check their chapters, and ping
|
|
||||||
packagers to check on package availability. As soon as pre-release
|
|
||||||
packages are available, ask people to start testing.
|
|
||||||
|
|
||||||
*Two to four weeks*
|
*Two to four weeks*
|
||||||
Ping Speciality Team leads to review and update release notes for
|
Ping subteam leads to review and update release notes for openstack-manuals.
|
||||||
openstack-manuals.
|
|
||||||
|
|
||||||
*At RC1*
|
*At RC1*
|
||||||
When projects create their branches and land the first patch,
|
When projects create their branches and land the first patch, they will
|
||||||
they will automatically have branch-specific documentation. After
|
automatically have branch-specific documentation.
|
||||||
the branches are created, create the project data file in the
|
|
||||||
``openstack-manuals`` repository for the new series.
|
|
||||||
|
|
||||||
*Before or on release day*
|
*Before or on release day*
|
||||||
Update the series settings in the template generator and add the
|
Create a project data file in the ``openstack-manuals`` repository for the
|
||||||
|
new series. Update the series settings in the template generator and add the
|
||||||
landing page for the next series by copying the templates from the
|
landing page for the next series by copying the templates from the
|
||||||
current release to the new release directory.
|
current release to the new release directory.
|
||||||
|
@ -5,11 +5,8 @@ Topic structure
|
|||||||
===============
|
===============
|
||||||
|
|
||||||
The OpenStack community welcomes all contributors to documentation. This
|
The OpenStack community welcomes all contributors to documentation. This
|
||||||
section provides recommendations on how to structure the content that you
|
section provides ideas on how to structure the content for an OpenStack
|
||||||
submit to the ``openstack-manuals`` repository.
|
project by using the principles of topic-based authoring.
|
||||||
|
|
||||||
Organize technical information in topics. Use the principles of topic-based
|
|
||||||
authoring in all technical publications.
|
|
||||||
|
|
||||||
Topic-based authoring is a method of content creation in which information
|
Topic-based authoring is a method of content creation in which information
|
||||||
is structured in small chunks of a particular type. In contrast to
|
is structured in small chunks of a particular type. In contrast to
|
||||||
|
@ -29,11 +29,6 @@ Contributor Guide
|
|||||||
* Updated guide to be relevant for updated openstack-manuals.
|
* Updated guide to be relevant for updated openstack-manuals.
|
||||||
* General bug fixes and updates.
|
* General bug fixes and updates.
|
||||||
|
|
||||||
API Guides
|
|
||||||
~~~~~~~~~~
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
|
||||||
Security Guide
|
Security Guide
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -41,40 +36,9 @@ Security Guide
|
|||||||
* Rework of 'node hardening' section
|
* Rework of 'node hardening' section
|
||||||
* Various fixes such as grammar and incorrect hyperlinks
|
* Various fixes such as grammar and incorrect hyperlinks
|
||||||
|
|
||||||
Training Guides
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
|
||||||
Training Labs
|
Training Labs
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
* Support for the new OpenStack release will be available shortly
|
* Support for the new OpenStack release will be available shortly
|
||||||
after the release of Pike.
|
after the release of Pike.
|
||||||
* Various bug fixes and minor improvements in the host scripts.
|
* Various bug fixes and minor improvements in the host scripts.
|
||||||
|
|
||||||
Translations
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Besides updating the existing translated manuals,
|
|
||||||
the Internationalization (i18n) team added the following new manuals:
|
|
||||||
|
|
||||||
* German:
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
|
||||||
* Indonesian:
|
|
||||||
|
|
||||||
* TBD.
|
|
||||||
|
|
||||||
* Japanese:
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
|
||||||
* Korean:
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
|
||||||
* Simplified Chinese:
|
|
||||||
|
|
||||||
* TBD
|
|
||||||
|
Loading…
Reference in New Issue
Block a user