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 <thanh.ha@linuxfoundation.org>

diff --git a/.coafile b/.coafile
index 48dbdab..74ead6f 100644 (file)
--- 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 (file)
index 0000000..f0d0179
--- /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 (file)
index 0000000..b2f80c5
--- /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 d9775d9..f6185f0 100644 (file)
--- 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 814b0f5..00b968f 100644 (file)
--- 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 (file)
index 5330b34..0000000
--- 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 666d8d4..13aeb3a 100644 (file)
--- 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: <major>.<minor>.<micro>[-<human-readable-tag>]
 
-    * 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.<minor>
     * 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 80be739..cfd78c8 100644 (file)
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
 click
 sphinx>=1.4.9
+sphinxcontrib-programoutput
 sphinx_bootstrap_theme>=0.4.14