From 741b7e3ec05d53cb29b38794982c5d1a7ef4836f Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Mon, 26 Jun 2017 14:17:50 -0400 Subject: [PATCH] update contributor guide based on changes after migration project Update the instructions to indicate which guides are no longer maintained by the docs team and how those docs are handled instead. Explain the data input to the www-generator.py tool Update the release instructions to explain how to update the templated portion of the site. Change-Id: I08bb228a6807bfcee0a6ab72ddaf229b455c9d1d Signed-off-by: Doug Hellmann --- .../source/blueprints-and-specs.rst | 67 ++++++++++++------- .../source/doc-tools/cli-reference.rst | 6 ++ .../source/doc-tools/config-reference.rst | 8 +++ .../source/doc-tools/scripts.rst | 8 ++- .../source/project-install-guide.rst | 24 +++++++ .../source/quickstart/new-projects.rst | 14 ++-- .../source/release/taskdetail.rst | 29 ++++---- 7 files changed, 109 insertions(+), 47 deletions(-) diff --git a/doc/contributor-guide/source/blueprints-and-specs.rst b/doc/contributor-guide/source/blueprints-and-specs.rst index 037a56a602..cf49a694a4 100644 --- a/doc/contributor-guide/source/blueprints-and-specs.rst +++ b/doc/contributor-guide/source/blueprints-and-specs.rst @@ -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 `_: 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 `_: 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//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-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 ----------------------- diff --git a/doc/contributor-guide/source/doc-tools/cli-reference.rst b/doc/contributor-guide/source/doc-tools/cli-reference.rst index 6102362e07..35a8941dd2 100644 --- a/doc/contributor-guide/source/doc-tools/cli-reference.rst +++ b/doc/contributor-guide/source/doc-tools/cli-reference.rst @@ -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 diff --git a/doc/contributor-guide/source/doc-tools/config-reference.rst b/doc/contributor-guide/source/doc-tools/config-reference.rst index 8764ad0286..5fcb7ae9ab 100644 --- a/doc/contributor-guide/source/doc-tools/config-reference.rst +++ b/doc/contributor-guide/source/doc-tools/config-reference.rst @@ -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 + `__. + 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 diff --git a/doc/contributor-guide/source/doc-tools/scripts.rst b/doc/contributor-guide/source/doc-tools/scripts.rst index 7794003840..3e8ac723b8 100644 --- a/doc/contributor-guide/source/doc-tools/scripts.rst +++ b/doc/contributor-guide/source/doc-tools/scripts.rst @@ -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 diff --git a/doc/contributor-guide/source/project-install-guide.rst b/doc/contributor-guide/source/project-install-guide.rst index a54371cfa9..23b6fdbd2a 100644 --- a/doc/contributor-guide/source/project-install-guide.rst +++ b/doc/contributor-guide/source/project-install-guide.rst @@ -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 `_. +.. 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 diff --git a/doc/contributor-guide/source/quickstart/new-projects.rst b/doc/contributor-guide/source/quickstart/new-projects.rst index d74af72362..6e7fc72c68 100644 --- a/doc/contributor-guide/source/quickstart/new-projects.rst +++ b/doc/contributor-guide/source/quickstart/new-projects.rst @@ -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`. diff --git a/doc/contributor-guide/source/release/taskdetail.rst b/doc/contributor-guide/source/release/taskdetail.rst index 2b886b64be..a8d0924853 100644 --- a/doc/contributor-guide/source/release/taskdetail.rst +++ b/doc/contributor-guide/source/release/taskdetail.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~