From: Thanh Ha Date: Wed, 8 Mar 2017 04:16:52 +0000 (-0500) Subject: Reformat lftools cmd docs for sphinx and click X-Git-Tag: v0.0.8~6 X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F52%2F4052%2F1;p=releng%2Flftools.git Reformat lftools cmd docs for sphinx and click Sphinx and Click have very different docstring formats unfortunately which makes it difficult for us to share the same documentation in both places without breaking the format of the other. This patch proposes a compromise where we use sphinxcontrib-programoutput to copy the output of Click --help documentation and place it inside of Sphinx. Not the best but ensures we only write documentation once. This patch also fixes the documentation for the Version command as it was inaccurate or misleading in some places. Also disable PyDocLint rule for backslashes since Click uses \b as a keyword for text wrapping. Change-Id: Ica09079d339065912fb5a78dccb24ee9a3063abc Signed-off-by: Thanh Ha --- diff --git a/.coafile b/.coafile index 48dbdab5..74ead6f8 100644 --- a/.coafile +++ b/.coafile @@ -9,6 +9,7 @@ use_spaces = yeah [Python] bears = BanditBear,PyCommentedCodeBear,PyDocStyleBear,PyFlakesBear,PyImportSortBear files = lftools/**/*.py +pydocstyle_ignore = D213, D301 [ShellCheck] bears = ShellCheckBear diff --git a/docs/commands/index.rst b/docs/commands/index.rst new file mode 100644 index 00000000..f0d01791 --- /dev/null +++ b/docs/commands/index.rst @@ -0,0 +1,11 @@ +######## +Commands +######## + +lftools is a collection of scripts written directly in python or externally via +bash. It supports the following commands. + +.. toctree:: + :maxdepth: 2 + + version diff --git a/docs/commands/version.rst b/docs/commands/version.rst new file mode 100644 index 00000000..b2f80c59 --- /dev/null +++ b/docs/commands/version.rst @@ -0,0 +1,26 @@ +******* +Version +******* + +.. program-output:: lftools version --help + +Commands +======== + +.. contents:: Version Commands + :local: + +bump +---- + +.. program-output:: lftools version bump --help + +patch +----- + +.. program-output:: lftools version patch --help + +release +------- + +.. program-output:: lftools version release --help diff --git a/docs/conf.py b/docs/conf.py index d9775d9a..f6185f0d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,7 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxcontrib.programoutput', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index 814b0f50..00b968f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 - shell + commands/index Indices and tables ================== diff --git a/docs/shell.rst b/docs/shell.rst deleted file mode 100644 index 5330b34d..00000000 --- a/docs/shell.rst +++ /dev/null @@ -1,5 +0,0 @@ -############## -Shell Commands -############## - -.. autofunction:: lftools.cli.version diff --git a/lftools/cli/version.py b/lftools/cli/version.py index 666d8d47..13aeb3a2 100644 --- a/lftools/cli/version.py +++ b/lftools/cli/version.py @@ -7,7 +7,7 @@ # which accompanies this distribution, and is available at # http://www.eclipse.org/legal/epl-v10.html ############################################################################## -"""Wrapper for version bash script.""" +"""Version bump script for Maven based projects.""" __author__ = 'Thanh Ha' @@ -24,15 +24,15 @@ import click def version(ctx): """Version bump script for Maven based projects. - Uses *release-tag* to bump versions for Maven projects. - In general, versions should be: ..[-] - * Human readable tag should not have any dots in it - * SNAPSHOT is used for development + \b + - Human readable tag should not have any dots in it + - SNAPSHOT is used for development - Scenarios:: + Scenarios: + \b master before release: x.y.z-SNAPSHOT (or x.y-SNAPSHOT in which case we treat it as x.y.0-SNAPSHOT) at release: x.y.z-Helium stable/helium after release: x.y.(z+1)-SNAPSHOT @@ -44,21 +44,10 @@ def version(ctx): Some things have a date for a version, e.g., 2014.09.24.4 + \b * We treat this as YYYY.MM.DD. * Note that all such dates currently in ODL are in YANG tools * They are all now YYYY.MM.DD.7 since 7 is the minor version for yangtools - - The goal of this script is to: - - #. take all x.y.z-SNAPSHOT to x.y.z-Helium - #. take all x.y.z-Helium versions to x.y.(z+1)-SNAPSHOT and - #. take all x.y.z-SNAPSHOT versions to x.(y+1).0-SNAPSHOT - - Commands: - - .. autofunction:: lftools.cli.version.bump - .. autofunction:: lftools.cli.version.release - .. autofunction:: lftools.cli.version.patch """ pass @@ -66,11 +55,15 @@ def version(ctx): @click.argument('release-tag') @click.pass_context def bump(ctx, release_tag): - """Version bump pom files in a Maven project by x.(y+1).z. + """Version bump pom files in a Maven project by x.(y+1).z or x.y.(z+1). + + This script performs version bumping as follows: - :arg str release-tag: When used for the 'bump' command it is the tag to - determine if a version should be bumped by x.(y+1).z (SNAPSHOT) or by - x.y.(z+1) (release-tag). + \b + 1. Change YYYY.MM.DD.y.z-SNAPSHOT to YYYY.MM.DD.(y+1).0-SNAPSHOT + 2. Change YYYY.MM.DD.y.z-Helium to YYMMDD.y.(z+1)-SNAPSHOT + 3. Change x.y.z-SNAPSHOT versions to x.(y+1).0-SNAPSHOT + 4. Change x.y.z-RELEASE_TAG versions to x.y.(z+1)-SNAPSHOT and """ subprocess.call(['version', 'bump', release_tag]) @@ -79,10 +72,10 @@ def bump(ctx, release_tag): @click.argument('release-tag') @click.pass_context def release(ctx, release_tag): - """Version bump pom files in a Maven project by x.y.(z+1). + """Version bump pom files in a Maven project from SNAPSHOT to RELEASE_TAG. - :arg str release-tag: When used for the 'release' command it is the - tag to use to bump all the versions to. + Searches poms for all instances of SNAPSHOT version and changes it to + RELEASE_TAG. """ subprocess.call(['version', 'release', release_tag]) @@ -90,17 +83,14 @@ def release(ctx, release_tag): @click.command() @click.argument('release-tag') @click.argument('patch-dir') -@click.option('--project', default='OpenDaylight') +@click.option('--project', default='OpenDaylight', + help='Project name to use when tagging. (Default: OpenDaylight)') @click.pass_context def patch(ctx, release_tag, patch_dir, project): - """Patch a project with git.bundles and then version bump by x.y.(z+1). - - :arg str release-tag: When used for the 'release' command it is the - tag to use to bump all the versions to. When used for the 'bump' - command it is the tag to determine if a version should be bumped by - x.1.z. - :arg str patch-dir: Path to where the taglist.log and git.bundles are - stored in the file system. + """Patch a project with git.bundles and then version bump. + + Applies git.bundle patches to the project and then performs a version bump + using RELEASE_TAG in order to version bump by x.y.(z+1)-SNAPSHOT. """ if not os.path.isdir(patch_dir): print("{} is not a valid directory.".format(patch_dir)) diff --git a/requirements.txt b/requirements.txt index 80be7391..cfd78c8a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ click sphinx>=1.4.9 +sphinxcontrib-programoutput sphinx_bootstrap_theme>=0.4.14