Skip to content

Commit ddc7650

Browse files
i-odeni-oden
authored
Merge pull request #277 from ScilifelabDataCentre/dev
Update docs and readme
2 parents fdd7388 + ea870ed commit ddc7650

7 files changed

Lines changed: 188 additions & 11 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,4 +87,5 @@ Please add a _short_ line describing the PR you make, if the PR implements a spe
8787
## Sprint (2022-02-23 - 2022-03-09)
8888
* Introduced a `--no-mail` flag in the CLI respectively a `send_email: True/False` json parameter to fix [issue 924](https://github.com/scilifelabdatacentre/dds_web/issues/924) ([#253](https://github.com/ScilifelabDataCentre/dds_cli/pull/253))
8989
* Added documentation and test protocol ([#252](https://github.com/ScilifelabDataCentre/dds_cli/pull/252))
90-
* Temporary unit option when adding user ([#261](https://github.com/ScilifelabDataCentre/dds_cli/pull/261))
90+
* Temporary unit option when adding user ([#261](https://github.com/ScilifelabDataCentre/dds_cli/pull/261))
91+
* Added windows docs (by Matthias Zepper) ([#276](https://github.com/ScilifelabDataCentre/dds_cli/pull/276))

‎README.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# SciLifeLab Data Delivery System - Command line interface
22

33
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
4-
[![install with PyPI](https://img.shields.io/badge/install%20with-PyPI-blue.svg)](https://pypi.org/project/dds_cli/)
4+
[![install with PyPI](https://img.shields.io/badge/install%20with-PyPI-blue.svg)](https://pypi.org/project/dds-cli/)
55

66
> **A command line tool `dds` to manage data and projects in the SciLifeLab Data Delivery Service.**
77
@@ -26,6 +26,39 @@ The `dds-cli` package can be installed from [PyPI](https://pypi.python.org/pypi/
2626
pip install dds-cli
2727
```
2828

29+
After installing, run `dds` and verify that the output looks like this:
30+
31+
```bash
32+
$ dds
33+
︵
34+
︵ ( ) ︵
35+
( ) ) ( ( ) SciLifeLab Data Delivery System
36+
︶ ( ) ) ( https://delivery.scilifelab.se/
37+
︶ ( ) Version 0.0.6
38+
︶
39+
Current user: dds_admin
40+
41+
Usage: dds [OPTIONS] COMMAND [ARGS]...
42+
43+
SciLifeLab Data Delivery System (DDS) command line interface.
44+
Access token is saved in a .dds_cli_token file in the home directory.
45+
46+
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
47+
│ --verbose -v Print verbose output to the console. │
48+
│ --log-file -l <filename> Save a log to a file. │
49+
│ --no-prompt Run without any interactive features. │
50+
│ --version Show the version and exit. │
51+
│ --help Show this message and exit. │
52+
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
53+
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
54+
│ auth Group command for creating and managing authenticated sessions. │
55+
│ data Group command for uploading, downloading and managing project data. │
56+
│ ls List the projects you have access to or the project contents. │
57+
│ project Group command for creating and managing projects within the DDS. │
58+
│ user Group command for managing user accounts, including your own. │
59+
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
60+
```
61+
2962
### Development version
3063
3164
If you would like the latest development version of tools, the command is:

‎dds_cli/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
__title__ = "Data Delivery System"
1616
__version__ = pkg_resources.get_distribution("dds_cli").version
17-
__url__ = "https://www.scilifelab.se/data"
17+
__url__ = "https://delivery.scilifelab.se/"
1818
__author__ = "SciLifeLab Data Centre"
1919
__author_email__ = "datacentre@scilifelab.se"
2020
__license__ = "MIT"

‎docs/index.rst‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,13 @@ How to use the DDS CLI
3838
Installation
3939
------------
4040

41+
At this time, a **Python** and **pip** installation is required for the ``dds-cli`` installation to work. We are currently working on an executable which can install all the requirements and the CLI for you. The goal is for this executable to be ready when we release the CLI into production.
42+
4143
Uppmax
4244
~~~~~~~
43-
We are currently checking that installing the DDS CLI on Rackham works as expected. We will update this information as soon as possible. Regarding Bianca: Uppmax has offered to help us out with testing that the connection to Bianca works. Instructions for this will therefore not be provided at this time. Data will be possible to deliver to Bianca when the DDS is in production. Instructions for how this will work will come at a later time.
45+
We are currently checking that installing the DDS CLI on Rackham works as expected. We will update this information as soon as possible. If we have not yet updated this section before you attempt to use the DDS CLI on **Uppmax Rackham**, feel free to try it and inform us on any issues.
46+
47+
**Regarding Bianca:** Uppmax has offered to help us out with testing that the connection to Bianca works. Instructions for this will therefore not be provided at this time. Data will be possible to deliver to Bianca when the DDS is in production. Instructions for how this will work will come at a later time.
4448

4549
PyPi - MacOS / Linux
4650
~~~~~~~~~~~~~~~~~~~~~
@@ -59,7 +63,15 @@ PyPi - MacOS / Linux
5963
python3 --version
6064
6165
If this does not return ``Python 3.8.x`` or higher, you will need to `install Python <https://www.python.org/downloads/>`_.
62-
66+
67+
.. warning::
68+
69+
Make sure you have the latest version of **pip**.
70+
71+
.. code-block::
72+
73+
python3 -m pip install --upgrade pip
74+
6375
2. To install the DDS CLI, open the terminal and run
6476

6577
.. code-block:: bash
@@ -137,7 +149,7 @@ See the test protocol and the command documentation :ref:`here<dds-ls>`.
137149

138150
How to test the web interface
139151
==============================
140-
The DDS web interface can be found at https://delivery.scilifelab.se/ (if you're met with an error message, try https://dds.dckube.scilifelab.se/ instead, and let us know that the first url does not work). There will only be a log in page and the possibility of requesting a password change. A guide on how to test out the existing web can be found :ref:`here<web>`.
152+
The DDS web interface can be found at https://delivery.scilifelab.se/. There will only be a log in page and the possibility of requesting a password change. A guide on how to test out the existing web can be found :ref:`here<web>`.
141153

142154
Command documentation and guide
143155
================================

‎docs/web.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ When another user invites you to the DDS, you will get an email (currently from
6767
2. Login
6868
""""""""""
6969

70-
2.1. Go to https://delivery.scilifelab.se/ (if you're met with an error message, try https://dds.dckube.scilifelab.se/ instead, and let us know that the first url does not work). You should see the following page.
70+
2.1. Go to https://delivery.scilifelab.se/. You should see the following page.
7171

7272
.. image:: _static/login.png
7373
:width: 400
@@ -83,7 +83,7 @@ When another user invites you to the DDS, you will get an email (currently from
8383
When the username and/or password is correct, a message should be displayed notifying you of the specific error.
8484

8585

86-
3. MFA Authentication
86+
1. MFA Authentication
8787
""""""""""""""""""""""
8888
3.1. When filling in the correct user credentials and clicking `Login`, you should be met with the following page:
8989

@@ -124,7 +124,7 @@ When another user invites you to the DDS, you will get an email (currently from
124124

125125
5. Reset forgotten password
126126
"""""""""""""""""""""""""""""
127-
5.1. Go to https://delivery.scilifelab.se/ (if you're met with an error message, try https://dds.dckube.scilifelab.se/ instead, and let us know that the first url does not work) and click on "Forgot Password?". You should be redirected to the following page:
127+
5.1. Go to https://delivery.scilifelab.se/ and click on "Forgot Password?". You should be redirected to the following page:
128128

129129
.. image:: _static/password_forgot.png
130130
:width: 400

‎docs/windows.rst‎

Lines changed: 123 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,126 @@
44
How to install the DDS CLI on Windows
55
======================================
66

7-
*Instructions for windows are coming*
7+
1. Download and install Python > 3.7
8+
======================================
9+
10+
a. Go to https://www.python.org/downloads/windows/
11+
12+
.. image:: _static/windows/python_install.png
13+
:align: center
14+
15+
b. In the left column, locate the **Windows installer** of a suitable version e.g. the **Python 3.9.10 - Jan. 14, 2022** release and download the associated .exe file.
16+
17+
.. image:: _static/windows/python_exe.png
18+
:align: center
19+
20+
.. note::
21+
22+
For most systems, the `Windows installer (64-bit) <https://www.python.org/ftp/python/3.9.10/python-3.9.10-amd64.exe>`_ will be the correct version. If your computer is older than a decade, chances are that you might need to select *32-bit binary* or a slightly older version of Python.
23+
24+
c. Click the downloaded **python-3.9.10-amd64.exe**. This will open the Python Installer.
25+
26+
.. image:: _static/windows/python_install-0.png
27+
:align: center
28+
29+
d. Make sure the **Add Python 3.9 to PATH** box is checked and proceed with the installation.
30+
31+
.. image:: _static/windows/python_install-1.png
32+
:align: center
33+
34+
.. image:: _static/windows/python_install-2.png
35+
:align: center
36+
37+
.. note::
38+
39+
For most users, the default installation options will work. On a shared or office computer, you might need to uncheck the Install launcher for all users, if you lack administrative privileges on the system. To do so, select the Customize installation option.
40+
41+
e. Click **Install Now** and follow the installer steps. You should be able to click next/continue on all steps. Python will be installed.
42+
43+
.. image:: _static/windows/python_install-3.png
44+
:align: center
45+
46+
.. image:: _static/windows/python_install-5.png
47+
:align: center
48+
49+
2. Proceed with a command line application / terminal
50+
=======================================================
51+
52+
a. From the start menu, launch the default command line application cmd or any other like the PowerShell.
53+
54+
.. image:: _static/windows/powershell_top-0.png
55+
:align: center
56+
57+
b. Verify that Python was installed successfully:
58+
59+
.. image:: _static/windows/powershell_top-1.png
60+
:align: center
61+
62+
.. note::
63+
64+
Upon entering ``python --version`` the version of the previously installed Python distribution should be shown. If a version number < 3.7 is shown or Python is not found, please consult the :ref:`Troubleshooting<troubleshooting>` section below.
65+
66+
c. Python ships with a helper program called **pip** to install additional packages. In the next step, this software should be upgraded to its current version.
67+
68+
.. image:: _static/windows/powershell-4.png
69+
:align: center
70+
71+
To upgrade pip, enter the command **python -m pip install --upgrade pip** to the terminal.
72+
73+
d. After pip was successfully upgraded, the Data Delivery System Command Line Interface can be installed:
74+
75+
.. image:: _static/windows/powershell_top-7.png
76+
:align: center
77+
78+
Enter **python -m pip install dds_cli** to start the install. Because several requirements will be automatically installed with the command line interface, several packages will be automatically downloaded:
79+
80+
.. image:: _static/windows/powershell-9.png
81+
:align: center
82+
83+
e. After the installation procedure has completed, the Data Delivery System Command Line Interface can be launched from the command line by entering **dds**. Please consult the general manual, how to interact with the CLI.
84+
85+
.. image:: _static/windows/powershell_top-10.png
86+
:align: center
87+
88+
.. _troubleshooting:
89+
90+
3. Troubleshooting
91+
====================
92+
93+
a. **Python not found or only in a wrong version.**
94+
95+
The most likely reason for this is an issue with the PATH variable, e.g. when the box Add Python 3.9 to Path was not checked during installation.
96+
97+
This can be manually checked and corrected via the Environment Variables.
98+
99+
.. image:: _static/windows/path-0.png
100+
:align: center
101+
102+
.. image:: _static/windows/path-1.png
103+
:align: center
104+
105+
Open the Environment Variables dialogue via the **Advanced** Tab in the **System Properties**.
106+
107+
.. image:: _static/windows/path-2.png
108+
:align: center
109+
110+
Select **Path** from the list of variables and click edit. Mind that there is a set of variables specific to the user on the top and a system-wide set of variables at the bottom. Both contain a **Path** and depending on the mode of installation, Python might be added to both or just one of them.
111+
112+
.. image:: _static/windows/path-4.png
113+
:align: center
114+
115+
Verify that the directories associated with the installation are present in the Path. If not, add the respective directories manually.
116+
117+
Use the search function first to verify where the Python installation has been added. Typically, all installation paths will contain your username and thus need to be customized. Change the paths shown in the example to: `C:\User\username\AppData ….`
118+
119+
b. **Security privileges required.**
120+
121+
It may be possible, that you will need to approve changes to your system explicitly during the install:
122+
123+
.. image:: _static/windows/windows_security.png
124+
:align: center
125+
126+
.. image:: _static/windows/python_install-4.png
127+
:align: center
128+
129+
In the latter case - depending on the installation directory - the combined length of all directories in PATH may exceed the length limit. Extending the allowed length should not negatively impact your system.

‎setup.py‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
from setuptools import setup, find_packages
22

3-
version = "0.0.5"
3+
version = "0.0.6"
44

55
with open("README.md") as f:
66
readme = f.read()
@@ -14,7 +14,16 @@
1414
description="A command line tool to manage data and projects in the SciLifeLab Data Delivery System.",
1515
long_description=readme,
1616
long_description_content_type="text/markdown",
17+
classifiers=[
18+
"Development Status :: 4 - Beta",
19+
"License :: OSI Approved :: MIT License",
20+
"Programming Language :: Python :: 3.7",
21+
"Programming Language :: Python :: 3.8",
22+
"Programming Language :: Python :: 3.9",
23+
"Programming Language :: Python :: 3.10",
24+
],
1725
url="https://github.com/ScilifelabDataCentre/dds_cli",
26+
author="SciLifeLab Data Centre",
1827
license="MIT",
1928
packages=find_packages(exclude=("docs")),
2029
include_package_data=True,

0 commit comments

Comments
 (0)