cli: improving docs. #227

roksys · 2019-01-17T14:16:46Z

Shorting too long headlines.
Closes cli: revise documentation #216

Signed-off-by: Rokas Maciulaitis rokas.maciulaitis@cern.ch

tiborsimko · 2019-01-17T14:55:16Z

reana_client/cli/files.py

-    help='Download all output files declared in the reana.yaml'
-         'specification or download files listed as '
+    help='Download workflow output files. Files are declared in the '
+         'reana.yaml specification or download files listed as '


We cannot use closes issue in the commit message until we add usage examples for commands, see the second part of the issue.

I am still working on it, that's why I moved it to 'In Work' column after I've made pull request.

Oh, I did not notice the status/milestone combo... We have been using "Need: work" label for indicate that.

If we all agree to use kanban as the main source of entry, then perhaps we can disabling automatic waffle bot rules that move statuses of things, and we can use only the manual method of moving cards between columns. (In this way we wouldn't need to add/remove "Need: work" label.)

Makes sense if the number of PRs-in-WIP is greater than the number of PRs-ready-for-review, which is indeed the case for early peer review and awareness.

tiborsimko · 2019-01-17T15:03:07Z

reana_client/cli/files.py

@@ -206,8 +206,8 @@ def download_files(ctx, workflow, filenames, output_directory, access_token):

 @click.command(
    'upload',
-    help='Upload all input sources declared in the reana.yaml'
-         'specification or upload files and directories listed as '
+    help='Upload workflow input files and sources. Files are declared in the '


Upload workflow input files and directories. The sources can be specified in the command line (see examples below). The default behaviour is to upload all input files and directories specified in the reana.yaml file.

(an example of a language we could use for all commands -- say what it does, what users can pass on, and what is happening by default, and finish by concrete examples people could copy/paste, as mentioned in the issue)

I like this simple phrasing, I would only simplify a bit more to
[short description]. [by default behaviour with mention to the example below].
But honestly I have checked git and kubectl as examples and they use the if not blahblah, command will blahblah and they are not necessary next to the short description, for instance in kubectl describe --help it is in the 2nd paragraph, see examples:

$ git checkout --help ... If no paths are given, git checkout will also update HEAD to set the specified branch as the current branch. ... $ kubectl describe --help ... If no such resource exists, it will output details for every resource that has a name prefixed with NAME PREFIX. ...

If it doesn't make sense to you @tiborsimko @roksys just ignore my #227 (comment) and related to default behaviour phrasing.

tiborsimko · 2019-01-17T15:05:17Z

reana_client/cli/workflow.py

@@ -154,8 +154,7 @@ def workflow_workflows(ctx, _filter, output_format, access_token,

 @click.command(
    'create',
-    help='Create a REANA compatible workflow from REANA '
-         'specifications file.')
+    help='Create a REANA compatible workflow.')


"Create a new analysis workflow..." since we are inside the REANA ecosystem, it is kind of clear that it will be REANA-compatible.

(I can go through all the texts later...)

tiborsimko · 2019-04-15T14:05:39Z

reana_client/cli/workflow.py

@@ -455,9 +473,7 @@ def add_verbose_data_from_response(response, verbose_headers,
                err=True)


-@workflow_execution_group.command(
-    'logs',
-    help='Get workflow logs.')


Add some body, e.g.

Retrieve logs of running workflow. Note that only finished steps of the workflow are returned, the logs of the currently processed step is not returned until it is finished.

... or better said in the usual optics:

The logs command permits to retrieve....

tiborsimko · 2019-04-15T14:07:15Z

reana_client/cli/workflow.py

+def workflow_validate(ctx, file):  # noqa: D301
+    """Validate workflow specification file.
+
+    The `validate` command permits to execute validation of workflow


That may be a bit ambiguous, better say something like:

The validate command permits to check syntax and validate the reana.yaml workflow specification file.

tiborsimko · 2019-04-15T14:09:07Z

reana_client/cli/workflow.py

-    """Stop given workflow."""
+def workflow_stop(ctx, workflow, force_stop, access_token):  # noqa: D301
+    """Stop a running workflow.
+


Add some body, e.g.

The stop command permits to hard-stop the running workflow process. Note that soft-stopping of the workflow is currently not supported. This command should be therefore used with care, only if you are absolutely sure that there is no point in continuing the running the workflow.

tiborsimko · 2019-04-15T14:09:40Z

reana_client/cli/workflow.py

+    """Create, upload and start a new analysis workflow.
+
+    The `run` command permits to create a new analysis workflow, upload its
+    input files and start it in one command.


Add a phrase:

It is a shortcut for create, upload and start chain of commands.

tiborsimko · 2019-04-15T14:11:10Z

reana_client/cli/workflow.py

+
+    Examples: \n
+    \t $ reana-client run \n
+    \t $ reana-client run -f reana.yaml -n workflow.6 code/helloworld.py


Is code/helloworld.py wanted there? A more common example may be:

reana-client run -n myanalysis-test-small -p myparam=mysmallvalue
reana-client run -n myanalysis-test-big -p myparam=mybigvalue

tiborsimko · 2019-04-15T14:14:43Z

reana_client/cli/workflow.py

+                    hard_delete, access_token):  # noqa: D301
+    """Delete a workflow.
+
+    By default removes all cached information of the given workflow and hides


The delete command permits to remove workflow runs from the database and the workspace. By default, the command removes the workflow and all its cached information and hides the workflow from the workflow list. Note that workflow workspace will still be accessible until you use --include-workspace flag. Note also that you can remove all past runs of a workflow by specifying -include-all-runs flag.

We don't have to mention --include-records explicitly in the text body, since this is not to be done normally by the end users... mostly by admins and developers. So it can stay only in the option help.

tiborsimko · 2019-04-15T14:15:23Z

reana_client/cli/workflow.py

+    remove its workspace.
+
+    Example: \n
+    \t $ reana-client delete -w workflow.13


myworkflow.42

and perhaps add one more example that would remove everything:

--inculde-.. --include-...

tiborsimko · 2019-04-15T14:16:54Z

reana_client/cli/workflow.py

+                  access_token, context_lines):  # noqa: D301
+    """Show diff between two worklows.
+
+    The `diff` command permits to compare two workflows. Workflow_a and


The diff command permits to compare two workflows, the workflow_a and workflow_b, which must be provided as arguments. The output will show the difference in workflow run parameters, the generated files, the logs, etc.

tiborsimko · 2019-04-15T14:17:28Z

reana_client/cli/workflow.py

+
+    Examples: \n
+    \t $ reana-client diff workflow.1 workflow.2 \n
+    \t $ reana-client diff workflow.1 workflow.2 --brief


myworkflow.42 myotherworkflow.21

tiborsimko · 2019-04-15T14:18:42Z

reana_client/cli/workflow.py

-                                      image, access_token):
-    """Open an interactive session inside the workflow workspace."""
+                                      image, access_token):  # noqa: D301
+    """Open an interactive session inside the workspace.


Add some body, e.g.

The open command permits to open interactive session processes on top of the workflow workspace, such as Jupyter notebooks. This is useful to quickly inspect and analyse the produced files while the workflow is stlil running.

tiborsimko · 2019-04-15T14:18:51Z

reana_client/cli/workflow.py

+    """Open an interactive session inside the workspace.
+
+    Examples:\n
+    \t $ reana-client open -w workflow.1 jupyter


myanalysis.42

tiborsimko · 2019-04-15T14:20:21Z

reana_client/cli/workflow.py

-    """Close an interactive workflow session."""
+def workflow_close_interactive_session(workflow, access_token):  # noqa: D301
+    """Close an interactive workflow session.
+


Add some body, e.g.

The close command permits to shut down any interactive sessions that you may have running. You would typically use this command after you finished exploring data in the Jupyter notebook and after you have transferred any code created in your interactive session.

tiborsimko · 2019-04-15T14:20:28Z

reana_client/cli/workflow.py

+    """Close an interactive workflow session.
+
+    Examples:\n
+    \t $ reana-client close -w workflow.1


myanalysis.42

tiborsimko · 2019-04-15T14:22:26Z

@roksys The docs are very nice and read great 👍 I left plenty of comments, but it is only for textual cosmetics

tiborsimko · 2019-04-15T15:43:34Z

reana_client/cli/files.py

+                   output_directory, access_token):  # noqa: D301
+    """Download workspace files.
+
+    This command permits to download workspace files. By default, the files


Please standardise everywhere the first sentence to:

The `download` command allows to... The `ls` commands lists... The `start` command allows to... The `status` command retrieves... ...

Also there is workflow.N still in many places instead of myanalysis.42:

$ git grep 'workflow\.[0-9]' docs/gettingstarted.rst: workflow.1 docs/gettingstarted.rst: $ reana-client status -w workflow.1 docs/gettingstarted.rst: $ export REANA_WORKON=workflow.1 docs/gettingstarted.rst: workflow.1 has been started. docs/userguide.rst: workflow.1 has been started. docs/userguide.rst: $ reana-client stop --force --workflow=otherworkflow.1 reana_client/cli/files.py: \t $ reana-client ls --workflow workflow.3 reana_client/cli/files.py: \t $ reana-client upload -w workflow.2 code/mycode.py reana_client/cli/files.py: \t $ reana-client rm -w workflow.4 data/mydata.csv \n reana_client/cli/workflow.py: \t $ reana-client start -w workflow.6 -p sleeptime=10 \n reana_client/cli/workflow.py: \t $ reana-client start -w workflow.6 -p myparam1=myvalue1 reana_client/cli/workflow.py: \t $ reana-client stop -w workflow.1 --force reana_client/cli/workflow.py: \t $ reana-client delete -w myworkflow.42 \n reana_client/cli/workflow.py: \t $ reana-client delete -w myworkflow.42 --include-records reana_client/cli/workflow.py: \t $ reana-client diff myworkflow.42 myotherworkflow.21 \n reana_client/cli/workflow.py: \t $ reana-client diff myworkflow.42 myotherworkflow.21 --brief reana_client/utils.py: Name might be in format 'reana.workflow.123' with arbitrary tests/test_cli_workflows.py: 'name': 'workflow.1', tests/test_cli_workflows.py: 'name': 'workflow.5', tests/test_cli_workflows.py: 'name': 'workflow.19', tests/test_cli_workflows.py: ['start', '-t', reana_token, '-w workflow.19', tests/test_cli_workflows.py: workflow = "workflow.1"

* Shorting too long headlines. Improving descriptions. Adding cmd examples. Closes reanahub#216 Signed-off-by: Rokas Maciulaitis <rokas.maciulaitis@cern.ch>

roksys added the Status: in work label Jan 17, 2019

roksys added this to the Someday milestone Jan 17, 2019

ghost assigned roksys Jan 17, 2019

ghost added Status: in review and removed Status: in work labels Jan 17, 2019

tiborsimko reviewed Jan 17, 2019

View reviewed changes

roksys added the Status: in work label Jan 17, 2019

tiborsimko reviewed Jan 17, 2019

View reviewed changes

roksys removed the Status: in review label Jan 17, 2019

ghost added Status: in review and removed Status: in work labels Jan 17, 2019

roksys added Status: in work and removed Status: in review labels Jan 17, 2019

roksys force-pushed the 216-cli-docs branch from d4f4acf to 18e186e Compare January 21, 2019 13:29

ghost added Status: in review and removed Status: in work labels Jan 21, 2019

roksys force-pushed the 216-cli-docs branch 5 times, most recently from b4614f9 to 389429f Compare January 21, 2019 15:51

diegodelemos modified the milestones: Someday, v0.5.0 Feb 1, 2019

roksys force-pushed the 216-cli-docs branch 6 times, most recently from 997cef0 to ec618c3 Compare February 4, 2019 12:21

tiborsimko reviewed Apr 15, 2019

View reviewed changes

roksys force-pushed the 216-cli-docs branch 6 times, most recently from 7fbf806 to ccbbd12 Compare April 15, 2019 15:22

tiborsimko reviewed Apr 15, 2019

View reviewed changes

roksys force-pushed the 216-cli-docs branch 3 times, most recently from b5a500c to 9542f1d Compare April 16, 2019 07:38

cli: improving docs.

d982de4

* Shorting too long headlines. Improving descriptions. Adding cmd examples. Closes reanahub#216 Signed-off-by: Rokas Maciulaitis <rokas.maciulaitis@cern.ch>

roksys force-pushed the 216-cli-docs branch from 9542f1d to d982de4 Compare April 16, 2019 07:52

tiborsimko approved these changes Apr 16, 2019

View reviewed changes

tiborsimko merged commit d982de4 into reanahub:master Apr 16, 2019

ghost removed the Status: in review label Apr 16, 2019

tiborsimko added this to Done in v0.5.0 Oct 7, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cli: improving docs. #227

cli: improving docs. #227

roksys commented Jan 17, 2019

tiborsimko Jan 17, 2019

roksys Jan 17, 2019

tiborsimko Jan 21, 2019

tiborsimko Jan 17, 2019

diegodelemos Feb 5, 2019

tiborsimko Jan 17, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko commented Apr 15, 2019

tiborsimko Apr 15, 2019

tiborsimko Apr 16, 2019

cli: improving docs. #227

cli: improving docs. #227

Conversation

roksys commented Jan 17, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tiborsimko commented Apr 15, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment