Skip to content

Commit c8640b6

Browse files
jmchiltonjmchilton
committed
Add IPython notebooks to docs.
 - One demonstrating planemo basics. - One demonstrating experimental CWL support. Lots of documentation updates.
1 parent c23569f commit c8640b6

24 files changed

+4847
-81
lines changed

‎docs/_writing_intro.rst‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ definitions for the input and output as well as an actual command template.
9898

9999
.. literalinclude:: writing/seqtk_seq_v2.xml
100100
:language: xml
101+
:emphasize-lines: 8-16
101102

102103
As shown above the command ``seqtk seq`` generates a help message for the
103104
``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.
116117
--example_input 2.fastq \
117118
--example_output 2.fasta \
118119
--test_case \
120+
--cite_url 'https://github.com/lh3/seqtk' \
119121
--help_from_command 'seqtk seq'
120122

121123
.. literalinclude:: writing/seqtk_seq_v3.xml
122124
:language: xml
125+
:emphasize-lines: 17-58
123126

124127
At this point we have a fairly a functional tool with test and help. This was
125128
a pretty simple example - usually you will need to put more work into the tool
@@ -133,30 +136,28 @@ with best practices.
133136
::
134137

135138
$ planemo l
136-
Linting tool /home/john/test/seqtk_seq.xml
137-
Applying linter lint_top_level... CHECK
139+
Linting tool /home/john/workspace/planemo/docs/notebooks/seqtk_seq.xml
140+
Applying linter top_level... CHECK
138141
.. CHECK: Tool defines a version.
139142
.. CHECK: Tool defines a name.
140143
.. CHECK: Tool defines an id name.
141-
Applying linter lint_tests... CHECK
144+
Applying linter tests... CHECK
142145
.. CHECK: 1 test(s) found.
143-
Applying linter lint_output... CHECK
144-
.. INFO: 1 output datasets found.
145-
Applying linter lint_inputs... CHECK
146+
Applying linter output... CHECK
147+
.. INFO: 1 outputs found.
148+
Applying linter inputs... CHECK
146149
.. INFO: Found 1 input parameters.
147-
Applying linter lint_help... CHECK
150+
Applying linter help... CHECK
148151
.. CHECK: Tool contains help section.
149152
.. CHECK: Help contains valid reStructuredText.
150-
Applying linter lint_command... CHECK
153+
Applying linter command... CHECK
151154
.. INFO: Tool contains a command.
152-
Applying linter lint_citations... WARNING
153-
.. WARNING: No citations found, consider adding citations to your tool.
155+
Applying linter citations... CHECK
156+
.. CHECK: Found 1 likely valid citations.
154157

155158
By default ``lint`` will find all the tools in your current working directory,
156159
but we could have specified a particular tool with ``planemo lint
157-
seqtk_seq.xml``. The only warning we received here is telling us that the tool
158-
lacks citation. Seqtk_ is unpublished, but if there was a paper to cite we
159-
could have done so by passing in the DOI_ (e.g. ``--doi '10.1101/010538'``).
160+
seqtk_seq.xml``.
160161

161162
Next we can run our tool's functional test with the ``test`` (or just ``t``)
162163
command. This will print a lot of output but should ultimately reveal our one

‎docs/commands.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ documentation describes these commands.
1111
.. include:: commands/brew_env.rst
1212
.. include:: commands/brew_init.rst
1313
.. include:: commands/config_init.rst
14+
.. include:: commands/cwl_run.rst
15+
.. include:: commands/cwl_script.rst
1416
.. include:: commands/dependency_script.rst
1517
.. include:: commands/docker_build.rst
1618
.. include:: commands/docker_shell.rst

‎docs/commands/cwl_run.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
2+
``cwl_run`` command
3+
======================================
4+
5+
This section is auto-generated from the help text for the planemo command
6+
``cwl_run``. This help message can be generated with ``planemo cwl_run
7+
--help``.
8+
9+
**Usage**::
10+
11+
planemo cwl_run [OPTIONS] TOOL_PATH JOB_PATH
12+
13+
**Help**
14+
15+
Planemo command for running CWL tools and jobs.
16+
17+
::
18+
19+
% planemo cwl_run cat1-tool.cwl cat-job.json
20+
21+
**Options**::
22+
23+
24+
--galaxy_root DIRECTORY Root of development galaxy directory to
25+
execute command with.
26+
--galaxy_sqlite_database DIRECTORY
27+
Preseeded Galaxy sqlite database to target.
28+
--install_galaxy Download and configure a disposable copy of
29+
Galaxy from github.
30+
--no_cache_galaxy Skip caching of Galaxy source and
31+
dependencies obtained with --install_galaxy.
32+
Not caching this results in faster downloads
33+
(no git) - so is better on throw away
34+
instances such with TravisCI.
35+
--no_cleanup Do not cleanup temp files created for and by
36+
Galaxy.
37+
--job_config_file PATH Job configuration file for Galaxy to target.
38+
--port INTEGER Port to serve Galaxy on (default is 9090).
39+
--host TEXT Host to bind Galaxy to. Default is 127.0.0.1
40+
that is restricted to localhost connections
41+
for security reasons set to 0.0.0.0 to bind
42+
Galaxy to all ports including potentially
43+
publicly accessible ones.
44+
--test_data DIRECTORY test-data directory to for specified
45+
tool(s).
46+
--tool_data_table PATH tool_data_table_conf.xml file to for
47+
specified tool(s).
48+
--dependency_resolvers_config_file PATH
49+
Dependency resolver configuration for Galaxy
50+
to target.
51+
--tool_dependency_dir DIRECTORY
52+
Tool dependency dir for Galaxy to target.
53+
--brew_dependency_resolution Configure Galaxy to use plain brew
54+
dependency resolution.
55+
--shed_dependency_resolution Configure Galaxy to use brewed Tool Shed
56+
dependency resolution.
57+
--cwl_galaxy_root DIRECTORY Root of development galaxy directory to
58+
execute command with (must be branch of
59+
Galaxy with CWL support, this option is
60+
experimental and will be replaced with
61+
--galaxy_root when and if CWL support is
62+
merged into Galaxy.
63+
--conformance-test Generate CWL conformance test object
64+
describing job. Required by CWL conformance
65+
test suite and implemented by cwltool
66+
reference implementation.
67+
--help Show this message and exit.
68+

‎docs/commands/cwl_script.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
2+
``cwl_script`` command
3+
======================================
4+
5+
This section is auto-generated from the help text for the planemo command
6+
``cwl_script``. This help message can be generated with ``planemo cwl_script
7+
--help``.
8+
9+
**Usage**::
10+
11+
planemo cwl_script [OPTIONS] TOOL_PATH JOB_PATH
12+
13+
**Help**
14+
15+
This compiles simple common workflow language workflows to a shell
16+
script.
17+
18+
**Options**::
19+
20+
21+
--no_container
22+
--output_dir PATH
23+
--base_dir PATH
24+
--help Show this message and exit.
25+

‎docs/commands/serve.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ instances.
3939

4040
--galaxy_root DIRECTORY Root of development galaxy directory to
4141
execute command with.
42+
--galaxy_sqlite_database DIRECTORY
43+
Preseeded Galaxy sqlite database to target.
4244
--install_galaxy Download and configure a disposable copy of
4345
Galaxy from github.
4446
--no_cache_galaxy Skip caching of Galaxy source and

‎docs/commands/shed_serve.rst‎

Lines changed: 45 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -23,46 +23,49 @@ logged into and explored interactively.
2323
**Options**::
2424

2525

26-
-r, --recursive Recursively perform command for nested repository
27-
directories.
28-
--fail_fast If multiple repositories are specified and an
29-
error occurs stop immediately instead of
30-
processing remaining repositories.
31-
--owner TEXT Tool Shed repository owner (username).
32-
--name TEXT Tool Shed repository name (defaults to the
33-
inferred tool directory name).
34-
--shed_email TEXT E-mail for Tool Shed auth (required unless
35-
shed_key is specified).
36-
--shed_key TEXT API key for Tool Shed access. An API key is
37-
required unless e-mail and password is specified.
38-
This key can be specified with either --shed_key
39-
or --shed_key_from_env.
40-
--shed_key_from_env TEXT Environment variable to read API key for Tool Shed
41-
access from.
42-
--shed_password TEXT Password for Tool Shed auth (required unless
43-
shed_key is specified).
44-
-t, --shed_target TEXT Tool Shed to target (this can be 'toolshed',
45-
'testtoolshed', 'local' (alias for
46-
http://localhost:9009/), an arbitrary url or
47-
mappings defined ~/.planemo.yml.
48-
--galaxy_root DIRECTORY Root of development galaxy directory to execute
49-
command with.
50-
--install_galaxy Download and configure a disposable copy of Galaxy
51-
from github.
52-
--no_cache_galaxy Skip caching of Galaxy source and dependencies
53-
obtained with --install_galaxy. Not caching this
54-
results in faster downloads (no git) - so is
55-
better on throw away instances such with TravisCI.
56-
--no_cleanup Do not cleanup temp files created for and by
57-
Galaxy.
58-
--job_config_file PATH Job configuration file for Galaxy to target.
59-
--port INTEGER Port to serve Galaxy on (default is 9090).
60-
--host TEXT Host to bind Galaxy to. Default is 127.0.0.1 that
61-
is restricted to localhost connections for
62-
security reasons set to 0.0.0.0 to bind Galaxy to
63-
all ports including potentially publicly
64-
accessible ones.
65-
--skip_dependencies Do not install shed dependencies as part of
66-
repository installation.
67-
--help Show this message and exit.
26+
-r, --recursive Recursively perform command for nested
27+
repository directories.
28+
--fail_fast If multiple repositories are specified and
29+
an error occurs stop immediately instead of
30+
processing remaining repositories.
31+
--owner TEXT Tool Shed repository owner (username).
32+
--name TEXT Tool Shed repository name (defaults to the
33+
inferred tool directory name).
34+
--shed_email TEXT E-mail for Tool Shed auth (required unless
35+
shed_key is specified).
36+
--shed_key TEXT API key for Tool Shed access. An API key is
37+
required unless e-mail and password is
38+
specified. This key can be specified with
39+
either --shed_key or --shed_key_from_env.
40+
--shed_key_from_env TEXT Environment variable to read API key for
41+
Tool Shed access from.
42+
--shed_password TEXT Password for Tool Shed auth (required unless
43+
shed_key is specified).
44+
-t, --shed_target TEXT Tool Shed to target (this can be 'toolshed',
45+
'testtoolshed', 'local' (alias for
46+
http://localhost:9009/), an arbitrary url or
47+
mappings defined ~/.planemo.yml.
48+
--galaxy_root DIRECTORY Root of development galaxy directory to
49+
execute command with.
50+
--galaxy_sqlite_database DIRECTORY
51+
Preseeded Galaxy sqlite database to target.
52+
--install_galaxy Download and configure a disposable copy of
53+
Galaxy from github.
54+
--no_cache_galaxy Skip caching of Galaxy source and
55+
dependencies obtained with --install_galaxy.
56+
Not caching this results in faster downloads
57+
(no git) - so is better on throw away
58+
instances such with TravisCI.
59+
--no_cleanup Do not cleanup temp files created for and by
60+
Galaxy.
61+
--job_config_file PATH Job configuration file for Galaxy to target.
62+
--port INTEGER Port to serve Galaxy on (default is 9090).
63+
--host TEXT Host to bind Galaxy to. Default is 127.0.0.1
64+
that is restricted to localhost connections
65+
for security reasons set to 0.0.0.0 to bind
66+
Galaxy to all ports including potentially
67+
publicly accessible ones.
68+
--skip_dependencies Do not install shed dependencies as part of
69+
repository installation.
70+
--help Show this message and exit.
6871

‎docs/commands/shed_test.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ This command requires the target to be version 15.07 or newer.
4848
mappings defined ~/.planemo.yml.
4949
--galaxy_root DIRECTORY Root of development galaxy directory to
5050
execute command with.
51+
--galaxy_sqlite_database DIRECTORY
52+
Preseeded Galaxy sqlite database to target.
5153
--install_galaxy Download and configure a disposable copy of
5254
Galaxy from github.
5355
--no_cache_galaxy Skip caching of Galaxy source and

‎docs/commands/test.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ please careful and do not try this against production Galaxy instances.
4949
previously.
5050
--galaxy_root DIRECTORY Root of development galaxy directory to
5151
execute command with.
52+
--galaxy_sqlite_database DIRECTORY
53+
Preseeded Galaxy sqlite database to target.
5254
--install_galaxy Download and configure a disposable copy of
5355
Galaxy from github.
5456
--no_cache_galaxy Skip caching of Galaxy source and

‎docs/commands/tool_factory.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ http://www.ncbi.nlm.nih.gov/pubmed/23024011.
2424

2525
--galaxy_root DIRECTORY Root of development galaxy directory to
2626
execute command with.
27+
--galaxy_sqlite_database DIRECTORY
28+
Preseeded Galaxy sqlite database to target.
2729
--install_galaxy Download and configure a disposable copy of
2830
Galaxy from github.
2931
--no_cache_galaxy Skip caching of Galaxy source and

‎docs/commands/tool_init.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Generate a tool outline from supplied arguments.
2020
--macros Generate a macros.xml for reuse across many tools.
2121
--test_case For use with --example_commmand, generate a tool
2222
test case from the supplied example.
23+
--cite_url TEXT Supply a URL for citation.
2324
--doi TEXT Supply a DOI (http://www.doi.org/) easing citation
2425
of the tool for Galxy users (e.g. 10.1101/014043).
2526
--container TEXT Add a Docker image identifier for this tool.

0 commit comments

Comments
 (0)