Docstring and documentation improvements.

jmchilton · jmchilton · commit 6e1e72615099 · 2016-04-11T20:35:28.000-04:00
- Add new ``planemo docs`` command to open Planemo docs in a web browser.
 - Add docstrings to all command modules.
diff --git a/docs/planemo.commands.rst b/docs/planemo.commands.rst
@@ -108,6 +108,14 @@ planemo.commands.cmd_docker_shell module
     :undoc-members:
     :show-inheritance:
 
+planemo.commands.cmd_docs module
+--------------------------------
+
+.. automodule:: planemo.commands.cmd_docs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 planemo.commands.cmd_lint module
 --------------------------------
 
diff --git a/planemo/cli.py b/planemo/cli.py
@@ -117,8 +117,17 @@ def get_command(self, ctx, name):
               envvar="PLANEMO_GLOBAL_WORKSPACE",
               help="Workspace for planemo.")
 @pass_context
-def planemo(ctx, config, directory, verbose):
-    """Utilities to assist with the development of Galaxy tools."""
+def planemo(ctx, config, directory, verbose):  # noqa
+    """A command-line toolkit for building tools and workflows for Galaxy.
+
+    Check out the full documentation for Planemo online
+    http://planemo.readthedocs.org or open with ``planemo docs``.
+    """
     ctx.verbose = verbose
     ctx.planemo_config = os.path.expanduser(config)
     ctx.planemo_directory = os.path.expanduser(directory)
+
+
+__all__ = [
+    "planemo",
+]
diff --git a/planemo/commands/cmd_brew.py b/planemo/commands/cmd_brew.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``brew`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_brew_env.py b/planemo/commands/cmd_brew_env.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``brew_env`` command."""
 from __future__ import print_function
 import click
 import os
diff --git a/planemo/commands/cmd_brew_init.py b/planemo/commands/cmd_brew_init.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``brew_init`` command."""
 import click
 
 import urllib
diff --git a/planemo/commands/cmd_conda_env.py b/planemo/commands/cmd_conda_env.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``conda_env`` command."""
 from __future__ import print_function
 import click
 
diff --git a/planemo/commands/cmd_conda_init.py b/planemo/commands/cmd_conda_init.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``conda_init`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_conda_install.py b/planemo/commands/cmd_conda_install.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``conda_install`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_config_init.py b/planemo/commands/cmd_config_init.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``config_init`` command."""
 import os
 import sys
 
diff --git a/planemo/commands/cmd_create_gist.py b/planemo/commands/cmd_create_gist.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``create_gist`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_cwl_run.py b/planemo/commands/cmd_cwl_run.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``cwl_run`` command."""
 import click
 from planemo.cli import pass_context
 from planemo import options
diff --git a/planemo/commands/cmd_cwl_script.py b/planemo/commands/cmd_cwl_script.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``cwl_script`` command."""
 from __future__ import print_function
 
 import click
diff --git a/planemo/commands/cmd_dependency_script.py b/planemo/commands/cmd_dependency_script.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``dependency_script`` command."""
 import os
 import sys
 
diff --git a/planemo/commands/cmd_docker_build.py b/planemo/commands/cmd_docker_build.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``docker_build`` command."""
 import click
 from planemo.cli import pass_context
 from planemo import options
diff --git a/planemo/commands/cmd_docker_shell.py b/planemo/commands/cmd_docker_shell.py
@@ -1,4 +1,6 @@
-"""The docker_shell command takes the path to a single tool file and returns
+"""Module describing the planemo ``docker_shell`` command.
+
+The docker_shell command takes the path to a single tool file and returns
 a new command to launch a new shell into the corresponding Docker container
 for that tool.
 
diff --git a/planemo/commands/cmd_docs.py b/planemo/commands/cmd_docs.py
@@ -0,0 +1,13 @@
+"""Module describing the planemo ``docs`` command."""
+import click
+
+from planemo.cli import pass_context
+
+SYNTAX_URL = "http://planemo.readthedocs.org/en/latest/"
+
+
+@click.command("syntax")
+@pass_context
+def cli(ctx, **kwds):
+    """Open the Planemo documentation in a web browser."""
+    click.launch(SYNTAX_URL)
diff --git a/planemo/commands/cmd_lint.py b/planemo/commands/cmd_lint.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``lint`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_normalize.py b/planemo/commands/cmd_normalize.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``normalize`` command."""
 from xml.etree import ElementTree
 
 import click
diff --git a/planemo/commands/cmd_project_init.py b/planemo/commands/cmd_project_init.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``project_init`` command."""
 import os
 import tempfile
 import shutil
diff --git a/planemo/commands/cmd_serve.py b/planemo/commands/cmd_serve.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``serve`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_share_test.py b/planemo/commands/cmd_share_test.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``share_test`` command."""
 import click
 
 from planemo.cli import pass_context
diff --git a/planemo/commands/cmd_shed_build.py b/planemo/commands/cmd_shed_build.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_build`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_shed_create.py b/planemo/commands/cmd_shed_create.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_create`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_shed_diff.py b/planemo/commands/cmd_shed_diff.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_diff`` command."""
 import sys
 import tempfile
 import shutil
diff --git a/planemo/commands/cmd_shed_download.py b/planemo/commands/cmd_shed_download.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_download`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_shed_init.py b/planemo/commands/cmd_shed_init.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``shed_init`` command."""
 import click
 import sys
 
diff --git a/planemo/commands/cmd_shed_lint.py b/planemo/commands/cmd_shed_lint.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``shed_lint`` command."""
 import click
 import sys
 
diff --git a/planemo/commands/cmd_shed_serve.py b/planemo/commands/cmd_shed_serve.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_serve`` command."""
 import time
 import click
 
diff --git a/planemo/commands/cmd_shed_test.py b/planemo/commands/cmd_shed_test.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_test`` command."""
 import socket
 import sys
 
diff --git a/planemo/commands/cmd_shed_update.py b/planemo/commands/cmd_shed_update.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_update`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_shed_upload.py b/planemo/commands/cmd_shed_upload.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``shed_upload`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_syntax.py b/planemo/commands/cmd_syntax.py
@@ -1,5 +1,4 @@
-"""
-"""
+"""Module describing the planemo ``syntax`` command."""
 import click
 
 from planemo.cli import pass_context
@@ -10,6 +9,5 @@
 @click.command("syntax")
 @pass_context
 def cli(ctx, **kwds):
-    """Open tool config syntax wiki page in a web browser.
-    """
+    """Open tool config syntax wiki page in a web browser."""
     click.launch(SYNTAX_URL)
diff --git a/planemo/commands/cmd_test.py b/planemo/commands/cmd_test.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``test`` command."""
 import sys
 
 import click
diff --git a/planemo/commands/cmd_test_reports.py b/planemo/commands/cmd_test_reports.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``test_reports`` command."""
 import os
 
 import click
diff --git a/planemo/commands/cmd_tool_factory.py b/planemo/commands/cmd_tool_factory.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``tool_factory`` command."""
 import os
 
 import click
diff --git a/planemo/commands/cmd_tool_init.py b/planemo/commands/cmd_tool_init.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``tool_init`` command."""
 import os
 import sys
 
diff --git a/planemo/commands/cmd_travis_before_install.py b/planemo/commands/cmd_travis_before_install.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``travis_before_install`` command."""
 import os
 import string
 
diff --git a/planemo/commands/cmd_travis_init.py b/planemo/commands/cmd_travis_init.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``travis_init`` command."""
 import os
 
 import click
diff --git a/planemo/commands/cmd_virtualenv.py b/planemo/commands/cmd_virtualenv.py
@@ -1,3 +1,4 @@
+"""Module describing the planemo ``virtualenv`` command."""
 import click
 
 from planemo.cli import pass_context

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	+"""Module describing the planemo ``brew`` command."""
`1`	`2`	`import click`
`2`	`3`
`3`	`4`	`from planemo.cli import pass_context`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	+"""Module describing the planemo ``brew_env`` command."""
`1`	`2`	`from __future__ import print_function`
`2`	`3`	`import click`
`3`	`4`	`import os`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	+"""Module describing the planemo ``conda_env`` command."""
`1`	`2`	`from __future__ import print_function`
`2`	`3`	`import click`
`3`	`4`