From c6a983fdc1b3a3ba27a164db4aa6c1fcf30129ca Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Tue, 6 Feb 2018 21:03:25 +0100 Subject: [PATCH] [doc-contrib-guide] Update release and install/deploy docs Remove outdated or unneeded information, particularly guide lists. Change-Id: I53cc71a9645a28e34b78aefea0ec53ae7db6520d --- .../source/blueprints-and-specs.rst | 324 +----------------- doc/doc-contrib-guide/source/doc-index.rst | 5 +- doc/doc-contrib-guide/source/docs-review.rst | 4 +- .../source/landing-pages.rst | 14 - .../source/project-deploy-guide.rst | 9 +- .../source/project-guides.rst | 1 - .../source/project-install-guide.rst | 30 +- .../source/release/taskdetail.rst | 28 +- .../source/release/taskoverview.rst | 19 +- .../source/topic-structure.rst | 7 +- releasenotes/source/pike.rst | 36 -- 11 files changed, 39 insertions(+), 438 deletions(-) delete mode 100644 doc/doc-contrib-guide/source/landing-pages.rst diff --git a/doc/doc-contrib-guide/source/blueprints-and-specs.rst b/doc/doc-contrib-guide/source/blueprints-and-specs.rst index c4c702ce76..3cadc1925a 100644 --- a/doc/doc-contrib-guide/source/blueprints-and-specs.rst +++ b/doc/doc-contrib-guide/source/blueprints-and-specs.rst @@ -1,36 +1,32 @@ .. _content-specs: -===================== -Content specification -===================== - +============================= Blueprints and specifications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================= The Documentation team uses specifications in the `docs-specs repository `_ to maintain large changes. Approved specifications are published at `Documentation Program Specifications `_. -For tracking purposes, a blueprint is created for each specification. It is -also good practice to contact the project team or subteam for the book you want -to change to discuss your changes before starting work. +For tracking purposes, a blueprint is created for each specification. 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 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 addition of the API reference site. -* For any large reorganization of a deliverable or set of deliverables. -* For automation work that needs to be designed prior to proposing a patch. -* For work that should definitely be discussed at a summit. +* For work that should definitely be discussed at a project teams gathering. A specification needs two +2 votes from the docs-specs-core team. See the current list of `docs-specs core team `_. -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 the bug. @@ -38,305 +34,3 @@ Use bugs against openstack-manuals or openstack-api-site: * For known errors in a document. 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 - `_: - Contains a reference listing of all configuration options for OpenStack - services by release version. -* `OpenStack 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 `_. -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 - `_: - A brief overview of how to send REST API requests to endpoints for - OpenStack services. -* `OpenStack Command-Line Interface Reference - `_: - Automatically generates help text for CLI commands and subcommands. -* `OpenStack End User Guide - `_: - 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 `_: - Complete reference listing of OpenStack REST APIs - with example requests and responses. -* `API specifications `_: - Within project's specification repos, some have opted - to document API specifications, such as Identity. -* `Object Storage API v1 - `_ - -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 `_ and -the `OpenStack API Bindings `_ -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 `_ -and the `built documentation `_. - -* `Infrastructure User 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//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-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//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//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 diff --git a/doc/doc-contrib-guide/source/doc-index.rst b/doc/doc-contrib-guide/source/doc-index.rst index 2a89b8e58f..eb2d461106 100644 --- a/doc/doc-contrib-guide/source/doc-index.rst +++ b/doc/doc-contrib-guide/source/doc-index.rst @@ -4,11 +4,12 @@ Landing pages on docs.openstack.org The main index pages on docs.openstack.org are part of the ``openstack-manuals`` repository in the ``www`` folder. These are -generated with using a :ref:`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 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 plug-in lists of networking or bare metal, the main project page diff --git a/doc/doc-contrib-guide/source/docs-review.rst b/doc/doc-contrib-guide/source/docs-review.rst index e85f7db572..fbfe65c64e 100644 --- a/doc/doc-contrib-guide/source/docs-review.rst +++ b/doc/doc-contrib-guide/source/docs-review.rst @@ -12,7 +12,7 @@ Reviewing documentation 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 review, use the `Documentation Program Dashboard -`_ or the appropriate list of +`_ or the appropriate list of Gerrit reviews for repositories with documentation. 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 Documentation project or the project's subteams, go to the `Documentation Program Dashboard - `_. + `_. To review patches for project teams' repositories, use the list of Gerrit changes for the appropriate project. diff --git a/doc/doc-contrib-guide/source/landing-pages.rst b/doc/doc-contrib-guide/source/landing-pages.rst deleted file mode 100644 index 75cd58950e..0000000000 --- a/doc/doc-contrib-guide/source/landing-pages.rst +++ /dev/null @@ -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 -`_ -in the openstack-manuals repository. - -See :ref:`template-generator` for details. diff --git a/doc/doc-contrib-guide/source/project-deploy-guide.rst b/doc/doc-contrib-guide/source/project-deploy-guide.rst index a9f4bdd497..3c4735883a 100644 --- a/doc/doc-contrib-guide/source/project-deploy-guide.rst +++ b/doc/doc-contrib-guide/source/project-deploy-guide.rst @@ -72,12 +72,6 @@ Setting up #. 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 OpenStack Infra ``project-config`` repository: @@ -118,6 +112,9 @@ OpenStack Infra ``project-config`` repository: #. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/doc-contrib-guide/source/project-guides.rst b/doc/doc-contrib-guide/source/project-guides.rst index 6f93cf343f..15e29ea8f5 100644 --- a/doc/doc-contrib-guide/source/project-guides.rst +++ b/doc/doc-contrib-guide/source/project-guides.rst @@ -86,4 +86,3 @@ by the documentation team. project-install-guide.rst project-deploy-guide.rst - landing-pages.rst diff --git a/doc/doc-contrib-guide/source/project-install-guide.rst b/doc/doc-contrib-guide/source/project-install-guide.rst index 02dcd0642b..c5cd3d8e1a 100644 --- a/doc/doc-contrib-guide/source/project-install-guide.rst +++ b/doc/doc-contrib-guide/source/project-install-guide.rst @@ -8,34 +8,25 @@ 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 +following the layout described in :doc:`project-guides`. 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 -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 +For the Newton and Ocata releases only, big tent projects created their own +installation guides, based on a standard template, in their own repository. +These guides were then centrally published to `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 `_. -If you would like to help out, `attend a meeting -`_. + The following instructions are superseded by :doc:`project-guides`. New + installation guides should be created using the layout defined in the spec, + rather than the following instructions. 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. #. 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. diff --git a/doc/doc-contrib-guide/source/release/taskdetail.rst b/doc/doc-contrib-guide/source/release/taskdetail.rst index 40c02d9e1f..0d8ecceef1 100644 --- a/doc/doc-contrib-guide/source/release/taskdetail.rst +++ b/doc/doc-contrib-guide/source/release/taskdetail.rst @@ -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 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 -review is needed to check that all major changes are in. Contact each -Specialty Team lead, listed at :doc:`../team-structure`, and ask them for -the notes for the books they look after. The source repository for release -notes is `openstack-manuals/releasenotes/source/RELEASENAME` and they are +review is needed to check that all major changes are in. Contact each subteam +lead, listed at :doc:`../team-structure`, and ask them for the notes for the +documentation they look after. The source for release notes is +``openstack-manuals/releasenotes/source/RELEASENAME.rst`` and they are published to -`https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html`. +``https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html``. .. _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 patches ready well ahead of the official release time. You can check the current gate status at `Zuul status - `_ to get an idea of the current + `_ to get an idea of the current merge times. Generate the site map @@ -203,23 +203,7 @@ To: This guide documents OpenStack Newton and Mitaka releases. -However, we will keep the documentation on the -`docs.openstack.org `_ -page for a while so that the users can refer the guides if necessary. - .. seealso:: See :ref:`docs_builds_eol` for instructions for building 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 diff --git a/doc/doc-contrib-guide/source/release/taskoverview.rst b/doc/doc-contrib-guide/source/release/taskoverview.rst index 06d9c2f5a5..b75ddbd8c7 100644 --- a/doc/doc-contrib-guide/source/release/taskoverview.rst +++ b/doc/doc-contrib-guide/source/release/taskoverview.rst @@ -10,24 +10,17 @@ Release day is usually 1300UTC on the `initial release date` listed on the *Four to six weeks before release* Ping packagers to locate pre-release packages to test the Installation - Guide 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. + Guides against, and start looking for willing volunteers to help test. *Two to four weeks* - Ping Speciality Team leads to review and update release notes for - openstack-manuals. + Ping subteam leads to review and update release notes for openstack-manuals. *At RC1* - When projects create their branches and land the first patch, - they will automatically have branch-specific documentation. After - the branches are created, create the project data file in the - ``openstack-manuals`` repository for the new series. + When projects create their branches and land the first patch, they will + automatically have branch-specific documentation. *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 current release to the new release directory. diff --git a/doc/doc-contrib-guide/source/topic-structure.rst b/doc/doc-contrib-guide/source/topic-structure.rst index a140e918e9..2fbd97e3e3 100644 --- a/doc/doc-contrib-guide/source/topic-structure.rst +++ b/doc/doc-contrib-guide/source/topic-structure.rst @@ -5,11 +5,8 @@ Topic structure =============== The OpenStack community welcomes all contributors to documentation. This -section provides recommendations on how to structure the content that you -submit to the ``openstack-manuals`` repository. - -Organize technical information in topics. Use the principles of topic-based -authoring in all technical publications. +section provides ideas on how to structure the content for an OpenStack +project by using the principles of topic-based authoring. Topic-based authoring is a method of content creation in which information is structured in small chunks of a particular type. In contrast to diff --git a/releasenotes/source/pike.rst b/releasenotes/source/pike.rst index 9e1be987c5..ec617460a8 100644 --- a/releasenotes/source/pike.rst +++ b/releasenotes/source/pike.rst @@ -29,11 +29,6 @@ Contributor Guide * Updated guide to be relevant for updated openstack-manuals. * General bug fixes and updates. -API Guides -~~~~~~~~~~ - -* TBD - Security Guide ~~~~~~~~~~~~~~ @@ -41,40 +36,9 @@ Security Guide * Rework of 'node hardening' section * Various fixes such as grammar and incorrect hyperlinks -Training Guides -~~~~~~~~~~~~~~~ - -* TBD - Training Labs ~~~~~~~~~~~~~ * Support for the new OpenStack release will be available shortly after the release of Pike. * 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