From e814f8befa509579aee4a7cef645508936f48098 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marco=20Vidal=20Garc=C3=ADa?= Date: Mon, 17 Jan 2022 18:03:49 +0100 Subject: [PATCH] global: use double backticks in docstrings - Highlighted expressions are compatible with both markdown (docs.reana.io) and reStructuredText (reana-client.readthedocs.io) --- README.rst | 2 +- reana_client/api/client.py | 4 +-- reana_client/cli/files.py | 20 +++++++-------- reana_client/cli/ping.py | 9 ++++--- reana_client/cli/quotas.py | 4 +-- reana_client/cli/workflow.py | 50 ++++++++++++++++++------------------ 6 files changed, 45 insertions(+), 44 deletions(-) diff --git a/README.rst b/README.rst index dd9181be..b26f5cf9 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,7 @@ REANA-Client About ===== -REANA-Client is a component of the `REANA `_ reusable and +REANA-Client is a component of the `REANA `_ reusable and reproducible research data analysis platform. It provides a command-line tool that allows researchers to submit, run, and manage their computational workflows. diff --git a/reana_client/api/client.py b/reana_client/api/client.py index 68a3d1f8..f03ddcce 100644 --- a/reana_client/api/client.py +++ b/reana_client/api/client.py @@ -736,8 +736,8 @@ def diff_workflows(workflow_id_a, workflow_id_b, brief, access_token, context_li :param context_lines: Optional parameter to set the number of context lines shown in the diff output. :param access_token: API token of user requesting diff. - :returns: A list of dictionaries composed by `asset`, `type`, `lines`, - `a` and `b`. Asset refers to the workflow asset where a + :returns: A list of dictionaries composed by ``asset``, ``type``, ``lines``, + ``a`` and ``b``. Asset refers to the workflow asset where a difference was found, type refers to the asset type, lines refer to the lines of the file where the differences are and a, b fields are the actual lines that differ. diff --git a/reana_client/cli/files.py b/reana_client/cli/files.py index d234b3eb..e0887e6b 100644 --- a/reana_client/cli/files.py +++ b/reana_client/cli/files.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # This file is part of REANA. -# Copyright (C) 2018, 2019, 2020, 2021 CERN. +# Copyright (C) 2018, 2019, 2020, 2021, 2022 CERN. # # REANA is free software; you can redistribute it and/or modify it # under the terms of the MIT License; see LICENSE file for more details. @@ -74,7 +74,7 @@ def files_group(ctx): help="Filter results to show only files that match certain filtering " "criteria such as file name, size or modification date." "Use `--filter =` pairs. " - "Available filters are `name`, `size` and `last-modified`.", + "Available filters are ``name``, ``size`` and ``last-modified``.", ) @click.argument("filename", metavar="SOURCE", nargs=1, required=False) @human_readable_or_raw_option @@ -95,9 +95,9 @@ def get_files( ): # noqa: D301 """List workspace files. - The `ls` command lists workspace files of a workflow specified by the + The ``ls`` command lists workspace files of a workflow specified by the environment variable REANA_WORKON or provided as a command-line flag - `--workflow` or `-w`. The SOURCE argument is optional and specifies a + ``--workflow`` or ``-w``. The SOURCE argument is optional and specifies a pattern matching files and directories. Examples: \n @@ -199,7 +199,7 @@ def download_files( ): # noqa: D301 """Download workspace files. - The `download` command allows to download workspace files and directories. + The ``download`` command allows to download workspace files and directories. By default, the files specified in the workflow specification as outputs are downloaded. You can also specify the individual files you would like to download, see examples below. @@ -274,7 +274,7 @@ def download_files( def upload_files(ctx, workflow, filenames, access_token): # noqa: D301 """Upload files and directories to workspace. - The `upload` command allows to upload workflow input files and + The ``upload`` command allows to upload workflow input files and directories. The SOURCES argument can be repeated and specifies which files and directories are to be uploaded, see examples below. The default behaviour is to upload all input files and directories specified in the @@ -360,7 +360,7 @@ def upload_files(ctx, workflow, filenames, access_token): # noqa: D301 def delete_files(ctx, workflow, filenames, access_token): # noqa: D301 """Delete files from workspace. - The `rm` command allow to delete files and directories from workspace. + The ``rm`` command allow to delete files and directories from workspace. Note that you can use glob to remove similar files. Examples:\n @@ -418,7 +418,7 @@ def delete_files(ctx, workflow, filenames, access_token): # noqa: D301 def move_files(ctx, source, target, workflow, access_token): # noqa: D301 """Move files within workspace. - The `mv` command allow to move the files within workspace. + The ``mv`` command allow to move the files within workspace. Examples:\n \t $ reana-client mv data/input.txt input/input.txt @@ -469,7 +469,7 @@ def move_files(ctx, source, target, workflow, access_token): # noqa: D301 help="Filter results to show only files that match certain filtering " "criteria such as file name or size." "Use `--filter =` pairs. " - "Available filters are `name` and `size`.", + "Available filters are ``name`` and ``size``.", ) @human_readable_or_raw_option @click.pass_context @@ -478,7 +478,7 @@ def workflow_disk_usage( ): # noqa: D301 """Get workspace disk usage. - The `du` command allows to chech the disk usage of given workspace. + The ``du`` command allows to chech the disk usage of given workspace. Examples: \n \t $ reana-client du -w myanalysis.42 -s \n diff --git a/reana_client/cli/ping.py b/reana_client/cli/ping.py index 5197abca..ec03a3f7 100644 --- a/reana_client/cli/ping.py +++ b/reana_client/cli/ping.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # This file is part of REANA. -# Copyright (C) 2017, 2018, 2019, 2020, 2021 CERN. +# Copyright (C) 2017, 2018, 2019, 2020, 2021, 2022 CERN. # # REANA is free software; you can redistribute it and/or modify it # under the terms of the MIT License; see LICENSE file for more details. @@ -31,7 +31,7 @@ def configuration_group(): def ping(ctx, access_token): # noqa: D301 """Check connection to REANA server. - The `ping` command allows to test connection to REANA server. + The ``ping`` command allows to test connection to REANA server. Examples: \n \t $ reana-client ping @@ -76,7 +76,7 @@ def ping(ctx, access_token): # noqa: D301 def version(ctx): # noqa: D301 """Show version. - The `version` command shows REANA client version. + The ``version`` command shows REANA client version. Examples: \n \t $ reana-client version @@ -99,7 +99,8 @@ def info(ctx, access_token: str, output_format: str): # noqa: D301 """List cluster general information. The ``info`` command lists general information about the cluster. - - Lists all the available workspaces. It also returns the default workspace + + Lists all the available workspaces. It also returns the default workspace defined by the admin. Examples: \n diff --git a/reana_client/cli/quotas.py b/reana_client/cli/quotas.py index 03760403..203fc10a 100644 --- a/reana_client/cli/quotas.py +++ b/reana_client/cli/quotas.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # This file is part of REANA. -# Copyright (C) 2020, 2021 CERN. +# Copyright (C) 2020, 2021, 2022 CERN. # # REANA is free software; you can redistribute it and/or modify it # under the terms of the MIT License; see LICENSE file for more details. @@ -67,7 +67,7 @@ def quota_show( ): # noqa: D301 """Show user quota. - The `quota-show` command displays quota usage for the user. + The ``quota-show`` command displays quota usage for the user. Examples: \n \t $ reana-client quota-show --resource disk --report limit\n diff --git a/reana_client/cli/workflow.py b/reana_client/cli/workflow.py index 3bfac4aa..285761f5 100644 --- a/reana_client/cli/workflow.py +++ b/reana_client/cli/workflow.py @@ -114,7 +114,7 @@ def workflow_execution_group(ctx): multiple=True, help="Filter workflow that contains certain filtering criteria. " "Use `--filter =` pairs. " - "Available filters are `name` and `status`.", + "Available filters are ``name`` and ``status``.", ) @click.option( "--include-progress", @@ -153,9 +153,9 @@ def workflow_workflows( # noqa: C901 ): # noqa: D301 """List all workflows and sessions. - The `list` command lists workflows and sessions. By default, the list of + The ``list`` command lists workflows and sessions. By default, the list of workflows is returned. If you would like to see the list of your open - interactive sessions, you need to pass the `--sessions` command-line + interactive sessions, you need to pass the ``--sessions`` command-line option. Example: \n @@ -309,7 +309,7 @@ def workflow_workflows( # noqa: C901 def workflow_create(ctx, file, name, skip_validation, access_token): # noqa: D301 """Create a new workflow. - The `create` command allows to create a new workflow from reana.yaml + The ``create`` command allows to create a new workflow from reana.yaml specifications file. The file is expected to be located in the current working directory, or supplied via command-line -f option, see examples below. @@ -390,12 +390,12 @@ def workflow_start( ): # noqa: D301 """Start previously created workflow. - The `start` command allows to start previously created workflow. The + The ``start`` command allows to start previously created workflow. The workflow execution can be further influenced by passing input prameters - using `-p` or `--parameters` flag and by setting additional operational - options using `-o` or `--options`. The input parameters and operational + using ``-p`` or ``--parameters`` flag and by setting additional operational + options using ``-o`` or ``--options``. The input parameters and operational options can be repetitive. For example, to disable caching for the Serial - workflow engine, you can set `-o CACHE=off`. + workflow engine, you can set ``-o CACHE=off``. Examples: \n \t $ reana-client start -w myanalysis.42 -p sleeptime=10 -p myparam=4 \n @@ -515,16 +515,16 @@ def workflow_restart( ): # noqa: D301 """Restart previously run workflow. - The `restart` command allows to restart a previous workflow on the same + The ``restart`` command allows to restart a previous workflow on the same workspace. Note that workflow restarting can be used in a combination with operational options ``FROM`` and ``TARGET``. You can also pass a modified workflow - specification with ``-f`` or `--file`` flag. + specification with ``-f`` or ``--file`` flag. - You can furthermore use modified input prameters using `-p` or - `--parameters` flag and by setting additional operational options using - `-o` or `--options`. The input parameters and operational options can be + You can furthermore use modified input prameters using ``-p`` or + ``--parameters`` flag and by setting additional operational options using + ``-o`` or ``--options``. The input parameters and operational options can be repetitive. Examples: \n @@ -631,7 +631,7 @@ def workflow_status( # noqa: C901 ): # noqa: D301 """Get status of a workflow. - The `status` command allow to retrieve status of a workflow. The status can + The ``status`` command allow to retrieve status of a workflow. The status can be created, queued, running, failed, etc. You can increase verbosity or filter retrieved information by passing appropriate command-line options. @@ -776,9 +776,9 @@ def workflow_logs( page=None, size=None, ): # noqa: D301 - """Get workflow logs. + """Get workflow logs. - The `logs` command allows to retrieve logs of running workflow. Note that + The ``logs`` command allows to 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. @@ -918,7 +918,7 @@ def workflow_validate( ): # noqa: D301 """Validate workflow specification file. - The `validate` command allows to check syntax and validate the reana.yaml + The ``validate`` command allows to check syntax and validate the reana.yaml workflow specification file. Examples: \n @@ -977,7 +977,7 @@ def workflow_validate( def workflow_stop(ctx, workflow, force_stop, access_token): # noqa: D301 """Stop a running workflow. - The `stop` command allows to hard-stop the running workflow process. Note + The ``stop`` command allows 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. @@ -1070,7 +1070,7 @@ def workflow_run( ): # noqa: D301 """Shortcut to create, upload, start a new workflow. - The `run` command allows to create a new workflow, upload its input files + The ``run`` command allows to create a new workflow, upload its input files and start it in one command. Examples: \n @@ -1126,12 +1126,12 @@ def workflow_run( def workflow_delete(ctx, workflow, all_runs, workspace, access_token): # noqa: D301 """Delete a workflow. - The `delete` command allows to remove workflow runs from the database and + The ``delete`` command allows 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. + ``--include-workspace`` flag. Note also that you can remove all past runs of + a workflow by specifying ``--include-all-runs`` flag. Example: \n \t $ reana-client delete -w myanalysis.42 \n @@ -1197,7 +1197,7 @@ def workflow_diff( ): # noqa: D301 """Show diff between two workflows. - The `diff` command allows to compare two workflows, the workflow_a and + The ``diff`` command allows 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. @@ -1294,7 +1294,7 @@ def workflow_open_interactive_session( ): # noqa: D301 """Open an interactive session inside the workspace. - The `open` command allows to open interactive session processes on top of + The ``open`` command allows 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. @@ -1348,7 +1348,7 @@ def workflow_open_interactive_session( def workflow_close_interactive_session(workflow, access_token): # noqa: D301 """Close an interactive session. - The `close` command allows to shut down any interactive sessions that you + The ``close`` command allows 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.