From ff2ca65e5c3b5ad2f2b60c2b367b5297854537f7 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Wed, 19 Jul 2017 09:39:38 +0000 Subject: [PATCH] Clean up rendered HTML with openstackdocstheme After migrating to openstackdocstheme, there are several points to be improved in the rendered HTML files. * Cleanup unnecessary vertical lines for quote blocks. Existing quote blocks are actually not intended and leading extra spaces cause this. This commit removes unnecessary leading spaces. * Some quote blocks are converted into definition lists to clean up vertical lines for quote blocks. * Use code-block for better code highlighting. * Specify maxdepth in user/index toctree. Change-Id: I9add5a317718e97abce15b5ddbfa3d1208a01570 --- CONTRIBUTING.rst | 9 +++------ doc/source/user/design.rst | 12 ++++++------ doc/source/user/index.rst | 1 + doc/source/user/sphinxext.rst | 14 +++----------- doc/source/user/usage.rst | 28 +++------------------------- 5 files changed, 16 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9a5eea2..e716304 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,17 +1,14 @@ If you would like to contribute to the development of OpenStack, you must follow the steps in this page: - - https://docs.openstack.org/infra/manual/developers.html +https://docs.openstack.org/infra/manual/developers.html If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool: - - https://docs.openstack.org/infra/manual/developers.html#development-workflow +https://docs.openstack.org/infra/manual/developers.html#development-workflow Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/reno +https://bugs.launchpad.net/reno diff --git a/doc/source/user/design.rst b/doc/source/user/design.rst index 4cd818c..2a1dd2a 100644 --- a/doc/source/user/design.rst +++ b/doc/source/user/design.rst @@ -39,12 +39,12 @@ We had several design inputs: containing a release note on a particular topic. * Release notes should be grouped by type in the output document. - 1. New features - 2. Known issues - 3. Upgrade notes - 4. Security fixes - 5. Bugs fixes - 6. Other + 1. New features + 2. Known issues + 3. Upgrade notes + 4. Security fixes + 5. Bugs fixes + 6. Other We want to eventually provide the ability to create a release notes file for a given release and add it to the source distribution for the diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 86c517d..3dc9ce2 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -3,6 +3,7 @@ ================= .. toctree:: + :maxdepth: 2 design usage diff --git a/doc/source/user/sphinxext.rst b/doc/source/user/sphinxext.rst index fb2c5f9..18a6d6d 100644 --- a/doc/source/user/sphinxext.rst +++ b/doc/source/user/sphinxext.rst @@ -23,44 +23,36 @@ Enable the extension by adding ``'reno.sphinxext'`` to the Options: *branch* - The name of the branch to scan. Defaults to the current branch. *reporoot* - The path to the repository root directory. Defaults to the directory where ``sphinx-build`` is being run. *relnotessubdir* - The path under ``reporoot`` where the release notes are. Defaults to ``releasenotes``. *notesdir* - The path under ``relnotessubdir`` where the release notes are. Defaults to ``notes``. *version* - A comma separated list of versions to include in the notes. The default is to include all versions found on ``branch``. *collapse-pre-releases* - A flag indicating that notes attached to pre-release versions should be incorporated into the notes for the final release, after the final release is tagged. *earliest-version* - A string containing the version number of the earliest version to be included. For example, when scanning a branch, this is typically set to the version used to create the branch to limit the output to only versions on that branch. *ignore-notes* - A string containing a comma-delimited list of filenames or UIDs for notes that should be ignored by the scanner. It is most useful to set this when a note is edited on the wrong branch, @@ -72,14 +64,14 @@ Examples The release notes for the "current" branch, with "Release Notes" as a title. -:: +.. code-block:: rest .. release-notes:: Release Notes The release notes for the "stable/liberty" branch, with a separate title. -:: +.. code-block:: rest ======================= Liberty Release Notes @@ -90,7 +82,7 @@ title. The release notes for version "1.0.0". -:: +.. code-block:: rest .. release-notes:: 1.0.0 Release Notes :version: 1.0.0 diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index 8dc58e6..22180e4 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -55,55 +55,46 @@ sections are configurable (see below) but default to the following list: prelude - General comments about the release. Prelude sections from all notes in a release are combined, in note order, to produce a single prelude introducing that release. This section is always included, regardless of what sections are configured. features - A list of new major features in the release. issues - A list of known issues in the release. For example, if a new driver is experimental or known to not work in some cases, it should be mentioned here. upgrade - A list of upgrade notes in the release. For example, if a database schema alteration is needed. deprecations - A list of features, APIs, configuration options to be deprecated in the release. Deprecations should not be used for something that is removed in the release, use upgrade section instead. Deprecation should allow time for users to make necessary changes for the removal to happen in a future release. critical - A list of *fixed* critical bugs. security - A list of *fixed* security issues. fixes - A list of other *fixed* bugs. other - Other notes that are important but do not fall into any of the given categories. Any sections that would be blank should be left out of the note file entirely. -:: +.. code-block:: yaml --- prelude: > @@ -141,8 +132,8 @@ not needed for the bullet items in the other sections of the template. To escape the text of any section and *retain* the newlines, prefix the value with ``|``. For example: -.. include:: ../../../examples/notes/add-complex-example-6b5927c246456896.yaml - :literal: +.. literalinclude:: ../../../examples/notes/add-complex-example-6b5927c246456896.yaml + :language: yaml See :doc:`examples` for the rendered version of the note. @@ -216,27 +207,23 @@ using command-line switches. For example: The following options are configurable: `notesdir` - The notes subdirectory within the `relnotesdir` where the notes live. Defaults to ``notes``. `collapse_pre_releases` - Should pre-release versions be merged into the final release of the same number (`1.0.0.0a1` notes appear under `1.0.0`). Defaults to ``True``. `stop_at_branch_base` - Should the scanner stop at the base of a branch (True) or go ahead and scan the entire history (False)? Defaults to ``True``. `branch` - The git branch to scan. If a stable branch is specified but does not exist, reno attempts to automatically convert that to an "end-of-life" tag. For example, ``origin/stable/liberty`` would be converted to ``liberty-eol``. @@ -244,7 +231,6 @@ The following options are configurable: Defaults to the "current" branch checked out. `earliest_version` - The earliest version to be included. This is usually the lowest version number, and is meant to be the oldest version. If unset, all versions will be scanned. @@ -252,18 +238,15 @@ The following options are configurable: Defaults to ``None``. `template` - The template used by reno new to create a note. `release_tag_re` - The regex pattern used to match the repo tags representing a valid release version. The pattern is compiled with the verbose and unicode flags enabled. Defaults to ``((?:[\d.ab]|rc)+)``. `pre_release_tag_re` - The regex pattern used to check if a valid release version tag is also a valid pre-release version. The pattern is compiled with the verbose and unicode flags enabled. The pattern must define a group called `pre_release` @@ -274,7 +257,6 @@ The following options are configurable: Defaults to ``(?P\.\d+(?:[ab]|rc)+\d*)$``. `branch_name_re` - The pattern for names for branches that are relevant when scanning history to determine where to stop, to find the "base" of a branch. Other branches are ignored. @@ -282,13 +264,11 @@ The following options are configurable: Defaults to ``stable/.+``. `sections` - The identifiers and names of permitted sections in the release notes, in the order in which the final report will be generated. A prelude section will always be automatically inserted before the first element of this list. `prelude_section_name` - The name of the prelude section in the note template. Note that the value for this must be a single word, but can have underscores. The value is displayed in titlecase in the report after replacing @@ -297,7 +277,6 @@ The following options are configurable: Defaults to ``prelude`` `ignore_null_merges` - OpenStack used to use null-merges to bring final release tags from stable branches back into the master branch. This confuses the regular traversal because it makes that stable branch appear to be @@ -312,7 +291,6 @@ The following options are configurable: Defaults to ``True``. `ignore_notes` - A list of filenames or UIDs for notes that should be ignored by the reno scanner. It is most useful to set this when a note is edited on the wrong branch, making it appear to be part of a release that it