Skip to content

Commit

Permalink
Updated developer docs for changed doc build; other docs build improv…
Browse files Browse the repository at this point in the history 
…ements

Details:

* Adjusted the 'releasing/starting a version' sections in the developmenti
  docs to the changed approach from the previous commit.

* Added galaxy API key to upload step.

* Changed the 'not the latest version' banner in the docs to consider the
  highest tag to be the latest version.

* Improved the description of the sphinx-versioning addon in conf.py.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
  • Loading branch information
@andy-maier
andy-maier committed Dec 14, 2020
1 parent 015158d commit d6cd87b
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 114 deletions.
75 changes: 34 additions & 41 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,63 +134,56 @@ def get_version(galaxy_file):
# ``sphinx-versioning`` command nor the ``scv_overflow`` are working.
scv_overflow = ("-D", "html_show_sphinx=False")

# Choosing to not generate documentation on any branch and rely solely on
# Github tags. Branches are whitelisted with option 'scv_whitelist_branches'.
# In other words, filter out any branches that don't match the pattern.
# List of Github branches that are included as versions in the documentation.
# This is in addition to the 'scv_whitelist_tags' option.
scv_whitelist_branches = ('master', 'stable_0.9')

# Since all branches are whitelisted, a 'root_ref' must be specified to avoid
# the error: "Root ref master not found in: v1.0.0 v1.1.0-beta1". The simplest
# solution is to provide a known tagged branch to serve as the root_ref such
# as 'v1.0.0'.
# UPDATE: Able to avoid 'root_ref' by setting property 'scv_recent_tag= True'
# thus commenting out scv_root_ref = 'v1.0.0'.
# The Github branch or tag that will be used as the version that is shown for
# the root URI of the documentation site.
scv_root_ref = 'master'

# Override root-ref to be the most recent committed tag. If no tags have docs
# then this option is ignored and --root-ref is used. Since we whitelist the
# master branch, we need to set a "root_ref" to avoid error
# "Root ref master not found in: v1.0.0 v1.1.0-beta1", See also 'scv_root_ref'.
# UPDATE: Able to avoid 'root_ref' by setting property 'scv_greatest_tag= True'
# thus commenting out scv_recent_tag = True'.
# scv_recent_tag = True
# Override the 'scv_root_ref' option to use the tag with the highest version
# number. If no tags have docs then this option is ignored and 'scv_root_ref'
# is used. Default is False.
scv_greatest_tag = True

# Override root-ref to be the tag with the highest version number. If no tags
# have docs then this option is ignored and --root-ref is used. Since we
# whitelist the master branch, we need to set a root_ref.
# See also 'scv_root_ref
# scv_greatest_tag = True
# Override the 'scv_root_ref' option to use the most recently committed tag.
# If no tags have docs then this option is ignored and 'scv_root_ref' is used.
# Default is False.
# scv_recent_tag = True

# White list which Git tags documentation will be generated and linked into the
# version selection box. This is currently a manual selection, until more
# versions are released, there are no regular expressions used.
# Keep these tags consistent with the docs.yml workflow.
# List of Github tags that are included as versions in the documentation.
# This is in addition to the 'scv_whitelist_branches' option.
scv_whitelist_tags = ('0.9.0',)

# Sort versions by one or more values. Valid values are semver, alpha, and time.
# Semantic is referred to as 'semver', this would ensure our latest VRM is
# the first in the list of documentation links.
scv_sort = ('semver',)

# Show a warning banner. Enables the Banner Message feature. Further info:
# Show a warning banner about not using the latest version. Default is False.
# Further info:
# https://sphinx-versions.readthedocs.io/en/latest/banner.html#banner
scv_show_banner = True

# The branch/tag considered to be the latest/current version. The banner will
# not be displayed in this ref, only in all others. Default is master.
# This can override the scv_banner_greatest_tag option, but given the greatest
# tag is currently desired behavior, this site will rely on
# 'scv_banner_greatest_tag = True' and not use 'scv_banner_main_ref'
scv_banner_main_ref = 'master'

# Override banner-main-ref to be the tag with the highest version number. If no
# tags have docs then this option is ignored and --banner-main-ref is used.
# The greatest tag is desirable behavior for this site.
# This documentation sets this to False because only ony version can have no
# banner, so it will be either on the latest released tagged version or on the
# master branch, and having the banner appear on either of them is confusing in
# a way.
# scv_show_banner = False

# The Github branch or tag considered to be the latest version for purposes
# of the warning banner. The banner will not be displayed in this ref, only in
# all others. Default is master.
# This can be overridden with the 'scv_banner_greatest_tag' option.
# scv_banner_main_ref = 'master'

# Override the 'scv_banner_main_ref' option to automatically use the tag with
# the highest version number. If no tags have docs then this option is ignored
# and 'scv_banner_main_ref' is used. Default is False.
# scv_banner_greatest_tag = True

# Temporary work around to promote the latest git tag in the banner, for some
# reason pre-release semantic versioning used with scv_banner_greatest_tag does
# not generate the correct latest banner.
# Override the 'scv_banner_main_ref' option to use the most recently committed
# tag. If no tags have docs then this option is ignored and
# 'scv_banner_main_ref' is used. Default is False.
# scv_banner_recent_tag = True

# Invert the order of branches/tags displayed in the sidebars in generated HTML
Expand Down
112 changes: 39 additions & 73 deletions docs/source/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -205,51 +205,53 @@ has the remote name ``origin`` in your local clone.
vi galaxy.yml
and set the 'version' parameter to the version to be released (replacing
the ``${...}`` variables with their values):
and set the 'version' parameter to the version to be released:

.. code-block:: yaml
version: ${MNU}
version: M.N.U
6. Edit the Sphinx config file:

.. code-block:: sh
vi docs/source/conf.py
and in the ``scv_whitelist_tags`` property, change the draft version
to the version to be released (replacing the ``${...}`` variables with
their values):
and in the ``scv_whitelist_tags`` property, add the version to be released:

.. # Note: Using python fails rstcheck on Python 3.5
.. code-block:: text
.. code-block:: python
scv_whitelist_tags = [ ...(previous versions)..., '${MNU}' ]
scv_whitelist_tags = [ ..., 'M.N.U' ]
If you are releasing the master branch, in addition increase the version of
the stable branch in the ``scv_whitelist_branches`` property to be the new
stable version:

.. code-block:: python
scv_whitelist_branches = ('master', 'stable_M.N')
7. Edit the GitHub workflow file docs.yml:

.. code-block:: sh
vi .github/workflows/docs.yml
and in the step named "Set the tag and branch variables for BRANCH",
change the draft version to the version to be released (replacing the
``${...}`` variables with their values):
and in the `on` section, increase the version of the stable branch to be
the new stable version:

.. code-block:: yaml
- name: Set the tag and branch variables for ${BRANCH}
if: ${{ github.ref == 'refs/heads/${BRANCH}' }}
run: |
echo "branch=${BRANCH}" >> $GITHUB_ENV
echo "tag=${MNU}" >> $GITHUB_ENV
on:
push:
# PR merge to these branches triggers this workflow
branches: [ master, stable_M.N ]
8. Commit your changes and push them upstream:

.. code-block:: sh
git add docs/source/release_notes.rst
git add docs/source/release_notes.rst galaxy.yml docs/source/conf.py .github/workflows/docs.yml
git commit -sm "Release ${MNU}"
git push --set-upstream origin release_${MNU}
Expand Down Expand Up @@ -305,11 +307,18 @@ has the remote name ``origin`` in your local clone.

16. Publish the collection to Ansible Galaxy:

You need to be registered on Ansible Galaxy, and your userid there needs to
be authorized to modify the 'ibm' namespace.

Look up your API Key on https://galaxy.ansible.com/me/preferences and upload
to galaxy while the `GALAXY_TOKEN` environment variable is set to your API
Key:

.. code-block:: sh
make upload
GALAXY_TOKEN={your-galaxy-api-key} make upload
This will show the package version and will ask for confirmation.
This will show the collection version and will ask for confirmation.

**Important:** Double check that the correct package version (``M.N.U``,
without any development suffix) is shown.
Expand Down Expand Up @@ -358,8 +367,6 @@ has the remote name ``origin`` in your local clone.
* ``MNU`` - Full version number M.N.U of the new version to be started
* ``MN`` - Major and minor version numbers M.N of that full version
* ``BRANCH`` - Name of the branch the new version is based upon
* ``MNUD`` - Full version number of the new version to be
started, plus draft version suffix, i.e. M.N.U-dev1

When starting a (major or minor) version (e.g. ``1.1.0``) based on the
master branch:
Expand All @@ -369,7 +376,6 @@ has the remote name ``origin`` in your local clone.
MNU=1.1.0
MN=1.0
BRANCH=master
MNUD=${MNU}-dev1
When starting an update (=fix) version (e.g. ``0.8.2``) based on a
stable branch:
Expand All @@ -379,7 +385,6 @@ has the remote name ``origin`` in your local clone.
MNU=0.8.2
MN=0.8
BRANCH=stable_${MN}
MNUD=${MNU}-dev1
3. Check out the branch the new version is based on, make sure it is up to
date with upstream, and create a topic branch for the new version:
Expand All @@ -398,12 +403,11 @@ has the remote name ``origin`` in your local clone.
vi docs/source/release_notes.rst
and insert the following section before the top-most section, and update
the version to the new version (replacing the ``${...}`` variables with
their values):
the version to the new version:

.. code-block:: rst
Version ${MNUD}
Version M.N.U-dev1
------------------
This version contains all fixes up to version M.N-1.x.
Expand Down Expand Up @@ -436,79 +440,41 @@ has the remote name ``origin`` in your local clone.

.. code-block:: yaml
version: ${MNUD}
version: M.N.U-dev1
Note: The version must follow the rules for semantic versioning 2.0
including the description of development/alpha/etc suffixes, as described
in https://semver.org/

6. Edit the Sphinx config file:

.. code-block:: sh
vi docs/source/conf.py
and in the ``scv_whitelist_tags`` property, add the new draft version to
the list (replacing the ``${...}`` variables with their values):

.. # Note: Using python fails rstcheck on Python 3.5
.. code-block:: text
scv_whitelist_tags = [ ...(previous versions)..., '${MNUD}' ]
7. Edit the GitHub workflow file docs.yml:

.. code-block:: sh
vi .github/workflows/docs.yml
and add a step for defining the variables for the new draft version after
the last such step (replacing the ``${...}`` variables with their values):

.. code-block:: yaml
- name: Set the tag and branch variables for ${BRANCH}
if: ${{ github.ref == 'refs/heads/${BRANCH}' }}
run: |
echo "branch=${BRANCH}" >> $GITHUB_ENV
echo "tag=${MNUD}" >> $GITHUB_ENV
8. Commit your changes and push them upstream:
6. Commit your changes and push them upstream:

.. code-block:: sh
git add docs/source/release_notes.rst
git add docs/source/release_notes.rst galaxy.yml
git commit -sm "Start ${MNU}"
git push --set-upstream origin start_${MNU}
9. Tag the branch with the new draft version and push the tag upstream:

.. code-block:: sh
git tag -f ${MNUD}
git push -f --tags
10. On GitHub, create a Pull Request for branch ``start_M.N.U``.
7. On GitHub, create a Pull Request for branch ``start_M.N.U``.

Important: When creating Pull Requests, GitHub by default targets the
``master`` branch. If you are starting based on a stable branch, you need
to change the target branch of the Pull Request to ``stable_M.N``.

11. On GitHub, create a milestone for the new version ``M.N.U``.
8. On GitHub, create a milestone for the new version ``M.N.U``.

You can create a milestone in GitHub via Issues -> Milestones -> New
Milestone.

12. On GitHub, go through all open issues and pull requests that still have
9. On GitHub, go through all open issues and pull requests that still have
milestones for previous releases set, and either set them to the new
milestone, or to have no milestone.

13. On GitHub, once the checks for this Pull Request succeed:
10. On GitHub, once the checks for this Pull Request succeed:

* Merge the Pull Request (no review is needed)
* Delete the branch of the Pull Request (``start_M.N.U``)

14. Checkout the branch the new version is based on, update it from upstream,
11. Checkout the branch the new version is based on, update it from upstream,
and delete the local topic branch you created:

.. code-block:: sh
Expand Down

0 comments on commit d6cd87b

Please sign in to comment.