Permalink
Browse files

Add IPython notebooks to docs.

 - One demonstrating planemo basics.
 - One demonstrating experimental CWL support.

Lots of documentation updates.
  • Loading branch information...
jmchilton committed Nov 2, 2015
1 parent c23569f commit c8640b65efe4bf27c4f785dd49d95af7c7ad1e78
@@ -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
@@ -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
@@ -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.
@@ -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.
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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.
Oops, something went wrong.

0 comments on commit c8640b6

Please sign in to comment.