Add IPython notebooks to docs.

- One demonstrating planemo basics. - One demonstrating experimental CWL support. Lots of documentation updates.
galaxyproject · Nov 2, 2015 · c8640b65efe4bf27c4f785dd49d95af7c7ad1e78 · c8640b6
1 parent c23569f
commit c8640b65efe4bf27c4f785dd49d95af7c7ad1e78
diff --git a/docs/_writing_intro.rst b/docs/_writing_intro.rst
@@ -98,6 +98,7 @@ definitions for the input and output as well as an actual command template.
 .. literalinclude:: writing/seqtk_seq_v2.xml
   :language: xml
+  
+   :emphasize-lines: 8-16
 As shown above the command ``seqtk seq`` generates a help message for the
 ``seq`` command. ``tool_init`` can take that help message and stick it right
@@ -116,10 +117,12 @@ away by the tool - but they can be a good place to start.
                        --example_input 2.fastq \
                        --example_output 2.fasta \
                        --test_case \
+  
+                        --cite_url 'https://github.com/lh3/seqtk' \
                        --help_from_command 'seqtk seq'
 .. literalinclude:: writing/seqtk_seq_v3.xml
   :language: xml
+  
+   :emphasize-lines: 17-58
 At this point we have a fairly a functional tool with test and help. This was
 a pretty simple example - usually you will need to put more work into the tool
@@ -133,30 +136,28 @@ with best practices.
 ::
    $ planemo l
-  
-    Linting tool /home/john/test/seqtk_seq.xml
-  
-    Applying linter lint_top_level... CHECK
+  
+    Linting tool /home/john/workspace/planemo/docs/notebooks/seqtk_seq.xml
+  
+    Applying linter top_level... CHECK
    .. CHECK: Tool defines a version.
    .. CHECK: Tool defines a name.
    .. CHECK: Tool defines an id name.
-  
-    Applying linter lint_tests... CHECK
+  
+    Applying linter tests... CHECK
    .. CHECK: 1 test(s) found.
-  
-    Applying linter lint_output... CHECK
-  
-    .. INFO: 1 output datasets found.
-  
-    Applying linter lint_inputs... CHECK
+  
+    Applying linter output... CHECK
+  
+    .. INFO: 1 outputs found.
+  
+    Applying linter inputs... CHECK
    .. INFO: Found 1 input parameters.
-  
-    Applying linter lint_help... CHECK
+  
+    Applying linter help... CHECK
    .. CHECK: Tool contains help section.
    .. CHECK: Help contains valid reStructuredText.
-  
-    Applying linter lint_command... CHECK
+  
+    Applying linter command... CHECK
    .. INFO: Tool contains a command.
-  
-    Applying linter lint_citations... WARNING
-  
-    .. WARNING: No citations found, consider adding citations to your tool.
+  
+    Applying linter citations... CHECK
+  
+    .. CHECK: Found 1 likely valid citations.
 By default ``lint`` will find all the tools in your current working directory,
 but we could have specified a particular tool with ``planemo lint
-  
-seqtk_seq.xml``. The only warning we received here is telling us that the tool
-  
-lacks citation. Seqtk_ is unpublished, but if there was a paper to cite we
-  
-could have done so by passing in the DOI_ (e.g. ``--doi '10.1101/010538'``).
+  
+seqtk_seq.xml``.
 Next we can run our tool's functional test with the ``test`` (or just ``t``)
 command. This will print a lot of output but should ultimately reveal our one

diff --git a/docs/commands.rst b/docs/commands.rst
@@ -11,6 +11,8 @@ documentation describes these commands.
 .. include:: commands/brew_env.rst
 .. include:: commands/brew_init.rst
 .. include:: commands/config_init.rst
+  
+.. include:: commands/cwl_run.rst
+  
+.. include:: commands/cwl_script.rst
 .. include:: commands/dependency_script.rst
 .. include:: commands/docker_build.rst
 .. include:: commands/docker_shell.rst

diff --git a/docs/commands/cwl_run.rst b/docs/commands/cwl_run.rst
@@ -0,0 +1,68 @@
+  
+
+  
+``cwl_run`` command
+  
+======================================
+  
+
+  
+This section is auto-generated from the help text for the planemo command
+  
+``cwl_run``. This help message can be generated with ``planemo cwl_run
+  
+--help``.
+  
+
+  
+**Usage**::
+  
+
+  
+    planemo cwl_run [OPTIONS] TOOL_PATH JOB_PATH
+  
+
+  
+**Help**
+  
+
+  
+Planemo command for running CWL tools and jobs.
+  
+
+  
+::
+  
+
+  
+    % planemo cwl_run cat1-tool.cwl cat-job.json
+  
+
+  
+**Options**::
+  
+
+  
+
+  
+      --galaxy_root DIRECTORY         Root of development galaxy directory to
+  
+                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
+  
+      --install_galaxy                Download and configure a disposable copy of
+  
+                                      Galaxy from github.
+  
+      --no_cache_galaxy               Skip caching of Galaxy source and
+  
+                                      dependencies obtained with --install_galaxy.
+  
+                                      Not caching this results in faster downloads
+  
+                                      (no git) - so is better on throw away
+  
+                                      instances such with TravisCI.
+  
+      --no_cleanup                    Do not cleanup temp files created for and by
+  
+                                      Galaxy.
+  
+      --job_config_file PATH          Job configuration file for Galaxy to target.
+  
+      --port INTEGER                  Port to serve Galaxy on (default is 9090).
+  
+      --host TEXT                     Host to bind Galaxy to. Default is 127.0.0.1
+  
+                                      that is restricted to localhost connections
+  
+                                      for security reasons set to 0.0.0.0 to bind
+  
+                                      Galaxy to all ports including potentially
+  
+                                      publicly accessible ones.
+  
+      --test_data DIRECTORY           test-data directory to for specified
+  
+                                      tool(s).
+  
+      --tool_data_table PATH          tool_data_table_conf.xml file to for
+  
+                                      specified tool(s).
+  
+      --dependency_resolvers_config_file PATH
+  
+                                      Dependency resolver configuration for Galaxy
+  
+                                      to target.
+  
+      --tool_dependency_dir DIRECTORY
+  
+                                      Tool dependency dir for Galaxy to target.
+  
+      --brew_dependency_resolution    Configure Galaxy to use plain brew
+  
+                                      dependency resolution.
+  
+      --shed_dependency_resolution    Configure Galaxy to use brewed Tool Shed
+  
+                                      dependency resolution.
+  
+      --cwl_galaxy_root DIRECTORY     Root of development galaxy directory to
+  
+                                      execute command with (must be branch of
+  
+                                      Galaxy with CWL support, this option is
+  
+                                      experimental and will be replaced with
+  
+                                      --galaxy_root when and if CWL support is
+  
+                                      merged into Galaxy.
+  
+      --conformance-test              Generate CWL conformance test object
+  
+                                      describing job. Required by CWL conformance
+  
+                                      test suite and implemented by cwltool
+  
+                                      reference implementation.
+  
+      --help                          Show this message and exit.
+  
+    
diff --git a/docs/commands/cwl_script.rst b/docs/commands/cwl_script.rst
@@ -0,0 +1,25 @@
+  
+
+  
+``cwl_script`` command
+  
+======================================
+  
+
+  
+This section is auto-generated from the help text for the planemo command
+  
+``cwl_script``. This help message can be generated with ``planemo cwl_script
+  
+--help``.
+  
+
+  
+**Usage**::
+  
+
+  
+    planemo cwl_script [OPTIONS] TOOL_PATH JOB_PATH
+  
+
+  
+**Help**
+  
+
+  
+This compiles simple common workflow language workflows to a shell
+  
+script.
+  
+
+  
+**Options**::
+  
+
+  
+
+  
+      --no_container
+  
+      --output_dir PATH
+  
+      --base_dir PATH
+  
+      --help             Show this message and exit.
+  
+    
diff --git a/docs/commands/serve.rst b/docs/commands/serve.rst
@@ -39,6 +39,8 @@ instances.
      --galaxy_root DIRECTORY         Root of development galaxy directory to
                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
      --install_galaxy                Download and configure a disposable copy of
                                      Galaxy from github.
      --no_cache_galaxy               Skip caching of Galaxy source and

diff --git a/docs/commands/shed_serve.rst b/docs/commands/shed_serve.rst
@@ -23,46 +23,49 @@ logged into and explored interactively.
 **Options**::
-  
-      -r, --recursive           Recursively perform command for nested repository
-  
-                                directories.
-  
-      --fail_fast               If multiple repositories are specified and an
-  
-                                error occurs stop immediately instead of
-  
-                                processing remaining repositories.
-  
-      --owner TEXT              Tool Shed repository owner (username).
-  
-      --name TEXT               Tool Shed repository name (defaults to the
-  
-                                inferred tool directory name).
-  
-      --shed_email TEXT         E-mail for Tool Shed auth (required unless
-  
-                                shed_key is specified).
-  
-      --shed_key TEXT           API key for Tool Shed access. An API key is
-  
-                                required unless e-mail and password is specified.
-  
-                                This key can be specified with either --shed_key
-  
-                                or --shed_key_from_env.
-  
-      --shed_key_from_env TEXT  Environment variable to read API key for Tool Shed
-  
-                                access from.
-  
-      --shed_password TEXT      Password for Tool Shed auth (required unless
-  
-                                shed_key is specified).
-  
-      -t, --shed_target TEXT    Tool Shed to target (this can be 'toolshed',
-  
-                                'testtoolshed', 'local' (alias for
-  
-                                http://localhost:9009/), an arbitrary url or
-  
-                                mappings defined ~/.planemo.yml.
-  
-      --galaxy_root DIRECTORY   Root of development galaxy directory to execute
-  
-                                command with.
-  
-      --install_galaxy          Download and configure a disposable copy of Galaxy
-  
-                                from github.
-  
-      --no_cache_galaxy         Skip caching of Galaxy source and dependencies
-  
-                                obtained with --install_galaxy. Not caching this
-  
-                                results in faster downloads (no git) - so is
-  
-                                better on throw away instances such with TravisCI.
-  
-      --no_cleanup              Do not cleanup temp files created for and by
-  
-                                Galaxy.
-  
-      --job_config_file PATH    Job configuration file for Galaxy to target.
-  
-      --port INTEGER            Port to serve Galaxy on (default is 9090).
-  
-      --host TEXT               Host to bind Galaxy to. Default is 127.0.0.1 that
-  
-                                is restricted to localhost connections for
-  
-                                security reasons set to 0.0.0.0 to bind Galaxy to
-  
-                                all ports including potentially publicly
-  
-                                accessible ones.
-  
-      --skip_dependencies       Do not install shed dependencies as part of
-  
-                                repository installation.
-  
-      --help                    Show this message and exit.
+  
+      -r, --recursive                 Recursively perform command for nested
+  
+                                      repository directories.
+  
+      --fail_fast                     If multiple repositories are specified and
+  
+                                      an error occurs stop immediately instead of
+  
+                                      processing remaining repositories.
+  
+      --owner TEXT                    Tool Shed repository owner (username).
+  
+      --name TEXT                     Tool Shed repository name (defaults to the
+  
+                                      inferred tool directory name).
+  
+      --shed_email TEXT               E-mail for Tool Shed auth (required unless
+  
+                                      shed_key is specified).
+  
+      --shed_key TEXT                 API key for Tool Shed access. An API key is
+  
+                                      required unless e-mail and password is
+  
+                                      specified. This key can be specified with
+  
+                                      either --shed_key or --shed_key_from_env.
+  
+      --shed_key_from_env TEXT        Environment variable to read API key for
+  
+                                      Tool Shed access from.
+  
+      --shed_password TEXT            Password for Tool Shed auth (required unless
+  
+                                      shed_key is specified).
+  
+      -t, --shed_target TEXT          Tool Shed to target (this can be 'toolshed',
+  
+                                      'testtoolshed', 'local' (alias for
+  
+                                      http://localhost:9009/), an arbitrary url or
+  
+                                      mappings defined ~/.planemo.yml.
+  
+      --galaxy_root DIRECTORY         Root of development galaxy directory to
+  
+                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
+  
+      --install_galaxy                Download and configure a disposable copy of
+  
+                                      Galaxy from github.
+  
+      --no_cache_galaxy               Skip caching of Galaxy source and
+  
+                                      dependencies obtained with --install_galaxy.
+  
+                                      Not caching this results in faster downloads
+  
+                                      (no git) - so is better on throw away
+  
+                                      instances such with TravisCI.
+  
+      --no_cleanup                    Do not cleanup temp files created for and by
+  
+                                      Galaxy.
+  
+      --job_config_file PATH          Job configuration file for Galaxy to target.
+  
+      --port INTEGER                  Port to serve Galaxy on (default is 9090).
+  
+      --host TEXT                     Host to bind Galaxy to. Default is 127.0.0.1
+  
+                                      that is restricted to localhost connections
+  
+                                      for security reasons set to 0.0.0.0 to bind
+  
+                                      Galaxy to all ports including potentially
+  
+                                      publicly accessible ones.
+  
+      --skip_dependencies             Do not install shed dependencies as part of
+  
+                                      repository installation.
+  
+      --help                          Show this message and exit.
diff --git a/docs/commands/shed_test.rst b/docs/commands/shed_test.rst
@@ -48,6 +48,8 @@ This command requires the target to be version 15.07 or newer.
                                      mappings defined ~/.planemo.yml.
      --galaxy_root DIRECTORY         Root of development galaxy directory to
                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
      --install_galaxy                Download and configure a disposable copy of
                                      Galaxy from github.
      --no_cache_galaxy               Skip caching of Galaxy source and

diff --git a/docs/commands/test.rst b/docs/commands/test.rst
@@ -49,6 +49,8 @@ please careful and do not try this against production Galaxy instances.
                                      previously.
      --galaxy_root DIRECTORY         Root of development galaxy directory to
                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
      --install_galaxy                Download and configure a disposable copy of
                                      Galaxy from github.
      --no_cache_galaxy               Skip caching of Galaxy source and

diff --git a/docs/commands/tool_factory.rst b/docs/commands/tool_factory.rst
@@ -24,6 +24,8 @@ http://www.ncbi.nlm.nih.gov/pubmed/23024011.
      --galaxy_root DIRECTORY         Root of development galaxy directory to
                                      execute command with.
+  
+      --galaxy_sqlite_database DIRECTORY
+  
+                                      Preseeded Galaxy sqlite database to target.
      --install_galaxy                Download and configure a disposable copy of
                                      Galaxy from github.
      --no_cache_galaxy               Skip caching of Galaxy source and

diff --git a/docs/commands/tool_init.rst b/docs/commands/tool_init.rst
@@ -20,6 +20,7 @@ Generate a tool outline from supplied arguments.
      --macros                  Generate a macros.xml for reuse across many tools.
      --test_case               For use with --example_commmand, generate a tool
                                test case from the supplied example.
+  
+      --cite_url TEXT           Supply a URL for citation.
      --doi TEXT                Supply a DOI (http://www.doi.org/) easing citation
                                of the tool for Galxy users (e.g. 10.1101/014043).
      --container TEXT          Add a Docker image identifier for this tool.