diff --git a/doc/contributor-guide/source/docs-builds.rst b/doc/contributor-guide/source/docs-builds.rst index ffddc1d7e7..bb31eed8dd 100644 --- a/doc/contributor-guide/source/docs-builds.rst +++ b/doc/contributor-guide/source/docs-builds.rst @@ -317,6 +317,8 @@ workstation. xml2po is part of the gnome-doc-utils and can be installed with :command:`yum install gnome-doc-utils` (on RedHat-based distributions), or :command:`zypper install xml2po` (on SUSE-based distributions). +.. _docs_builds_eol: + Building docs from end-of-life releases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/contributor-guide/source/release/taskdetail.rst b/doc/contributor-guide/source/release/taskdetail.rst index ea5792d27a..384bcee6f5 100644 --- a/doc/contributor-guide/source/release/taskdetail.rst +++ b/doc/contributor-guide/source/release/taskdetail.rst @@ -81,10 +81,59 @@ Make the following changes in the **openstack-manuals** repository: $ cp -a www/RELEASE www/NEXT_SERIES -#. Update the ``RELEASED_SERIES``, ``SERIES_IN_DEVELOPMENT``, and - ``FUTURE_SERIES`` values in the template generator +#. Update the ``PAST_SERIES``, ``RELEASED_SERIES``, + ``SERIES_IN_DEVELOPMENT``, and ``FUTURE_SERIES`` values at the top + of the source file for the template generator (``tools/www-generator.py``). + * Add the existing value of the ``RELEASED_SERIES`` variable to the + ``PAST_SERIES`` list. + * Set the ``RELEASED_SERIES`` variable to the name of the series + being released. + * Set the ``SERIES_IN_DEVELOPMENT`` variable to the name of the + next series. + * Add any additional known names to the ``FUTURE_SERIES`` list. + + For example, at the end of the Pike cycle, the variables will + contain: + + .. code-block:: python + + PAST_SERIES = [ + 'kilo', + 'liberty', + 'mitaka', + 'newton', + ] + RELEASED_SERIES = 'ocata' + SERIES_IN_DEVELOPMENT = 'pike' + FUTURE_SERIES = [ + 'queens', + ] + + To update the settings: + + * ``'ocata'`` is added to ``PAST_SERIES`` + * ``RELEASED_SERIES`` changes from ``'ocata'`` to ``'pike'`` + * ``SERIES_IN_DEVELOPMENT`` becomes ``'queens'`` + * ``'queens'`` is removed from the ``FUTURE_SERIES`` list + * ``'rocky'`` is added to the ``FUTURE_SERIES`` list + + .. code-block:: python + + PAST_SERIES = [ + 'kilo', + 'liberty', + 'mitaka', + 'newton', + 'ocata', + ] + RELEASED_SERIES = 'pike' + SERIES_IN_DEVELOPMENT = 'queens' + FUTURE_SERIES = [ + 'rocky', + ] + This will cause docs.openstack.org to redirect to the series-specific landing page for the current release, and the templates for the release being completed will use the data from @@ -95,7 +144,8 @@ Make the following changes in the **openstack-manuals** repository: If any project links are missing and cause the template generator to fail, set the flags to disable linking to those docs. For example, if "foo" does not have a configuration reference guide, - set ``has_config_ref: false`` for the "foo" project. + set ``has_config_ref: false`` for the "foo" project by modifying + the file created in step 1. .. warning:: @@ -155,3 +205,20 @@ To: 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/tools/www-generator.py b/tools/www-generator.py index c7db4b736c..73aa0e21ea 100755 --- a/tools/www-generator.py +++ b/tools/www-generator.py @@ -27,18 +27,29 @@ import requests import yaml +# List released series for which documentation is still published. PAST_SERIES = [ 'kilo', 'liberty', 'mitaka', 'newton', ] + +# Set RELEASED_SERIES to the most current release that is not in +# active development. RELEASED_SERIES = 'ocata' + +# Set SERIES_IN_DEVELOPMENT to the name of the series being developed +# right now. SERIES_IN_DEVELOPMENT = 'pike' + +# List any names known for future releases here. FUTURE_SERIES = [ 'queens', 'rocky', ] + +# Do not modify this variable. ALL_SERIES = ( PAST_SERIES + [RELEASED_SERIES, SERIES_IN_DEVELOPMENT] +