Merge pull request #37 from ssciwr/update_docs

update docs

Author: lkeegan

README.md

@@ -1,75 +1,51 @@
 # mease-elabftw
 
+[![pypi](https://img.shields.io/pypi/v/mease-elabftw.svg)](https://pypi.org/project/mease-elabftw)
+[![docs](https://readthedocs.org/projects/mease-elabftw/badge/?version=latest)](https://mease-elabftw.readthedocs.io/en/latest/?badge=latest)
 [![tests](https://github.com/ssciwr/mease-elabftw/workflows/Tests/badge.svg)](https://github.com/ssciwr/mease-elabftw/actions?query=workflow%3ATests)
 [![codecov](https://codecov.io/gh/ssciwr/mease-elabftw/branch/main/graph/badge.svg?token=xJTHCFXzrz)](https://codecov.io/gh/ssciwr/mease-elabftw)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ssciwr_mease-elabftw&metric=alert_status)](https://sonarcloud.io/dashboard?id=ssciwr_mease-elabftw)
-[![Documentation Status](https://readthedocs.org/projects/mease-elabftw/badge/?version=latest)](https://mease-elabftw.readthedocs.io/en/latest/?badge=latest)
+[![sonar](https://sonarcloud.io/api/project_badges/measure?project=ssciwr_mease-elabftw&metric=alert_status)](https://sonarcloud.io/dashboard?id=ssciwr_mease-elabftw)
 
-Python library for interacting with [eLabFTW](https://www.elabftw.net/) experiments:
+A Python library for interacting with [eLabFTW](https://www.elabftw.net/) experiments:
 
 - Create [NWB](https://nwb-schema.readthedocs.io/en/latest/) metadata from an eLabFTW experiment
-- Extract [metadata](https://doc.elabftw.net/metadata.html) from linked database items
 - Upload files (e.g. analysis result from HPC) to an eLabFTW experiment
 - List eLabFTW experiments from the command line
 
 ## Setup
 
-To install:
-
 ```bash
-python -m pip install git+https://github.com/ssciwr/mease-elabftw
+python -m pip install mease-elabftw
 ```
 
-You also need to generate an API key in eLabFTW (User Panel -> API Keys -> GENERATE AN API KEY),
+To authenticate requests to the eLabFTW server you also need to generate an API key in eLabFTW (User Panel -> API Keys -> GENERATE AN API KEY),
 and then set the environment variable `ELABFTW_TOKEN` to this key, e.g.
 
 ```bash
 export ELABFTW_TOKEN=abc123abc123abc123
 ```
 
-This key is needed to authenticate requests to the eLabFTW server.
-
 ## Use in Python
 
 Get nwb metadata from an elabftw experiment to use in [mease-lab-to-nwb](https://github.com/ssciwr/mease-lab-to-nwb):
 
 ```pycon
 >>> import mease_elabftw
->>> from pprint import pprint
->>> pprint(mease_elabftw.list_experiments("Liam"))
-['163: test fake experiment without json metadata (Liam Keegan, 2021-10-07)',
- '156: test fake experiment with json metadata (Liam Keegan, 2021-10-01)']
->>> pprint(mease_elabftw.get_nwb_metadata(156))
-{'Ecephys': {},
- 'NWBFile': {'experimenter': 'Liam Keegan',
-             'identifier': '20211001-8b6f100d66f4312d539c52620f79d6a503c1e2d1',
-             'institution': 'Heidelberg University, Physiology and '
-                            'Pathophysiology',
-             'lab': 'Medical Biophysics, Groh/Mease',
-             'session_description': 'test fake experiment with json metadata',
-             'session_start_time': '2021-10-01 11:13:47',
-             'virus': 'AAVretr ChR2-tdTomato:\n'
-                      '  * Virus in -80 storage: AAVrg-CAG-hChR2-tdTomato (AAV '
-                      'Retrograde)\n'
-                      '  * Origin: Addgene\n'
-                      '  * Comments: retrograde\n'
-                      '  * Expression Quality: \n'
-                      '  * product number: \n'
-                      'AAVretr Flpo:\n'
-                      '  * Virus in -80 storage: AAVretr EF1a-Flpo\n'
-                      '  * Origin: Addgene\n'
-                      '  * Comments: retrograde Flip\n'
-                      '  * Expression Quality: \n'
-                      '  * product number: 55637-AAVrg\n'},
- 'Subject': {}}
+>>> mease_elabftw.list_experiments("Liam")
+['163: test fake experiment without json metadata (Liam Keegan, 2021-10-07)', '156: test fake experiment with json metadata (Liam Keegan, 2021-10-01)']
+>>> metadata = mease_elabftw.get_nwb_metadata(156)
+>>> metadata["NWBFile"]["session_description"]
+test fake experiment with json metadata
+>>> metadata["NWBFile"]["identifier"]
+20211001-8b6f100d66f4312d539c52620f79d6a503c1e2d1
 ```
 
 ## Use from terminal
 
 List all experiments on elabftw belonging to user "Liam":
 
 ```bash
-liam@ssc:~$ elabftw-list Liam
+$ elabftw-list Liam
 163: test fake experiment without json metadata (Liam Keegan, 2021-10-07)
 156: test fake experiment with json metadata (Liam Keegan, 2021-10-01)
 ```

docs/cli.rst

@@ -0,0 +1,25 @@
+Command Line Interface
+======================
+
+The ``elabftw-list`` command prints a list of experiments:
+
+.. code-block:: bash
+
+   $ elabftw-list --help
+   Usage: elabftw-list [OPTIONS] [OWNER]
+
+     Prints a list of eLabFTW experiments belonging to OWNER
+
+     If OWNER is not specified, all experiments are printed.
+
+   Options:
+     --help  Show this message and exit.
+
+
+Example of use:
+
+.. code-block:: bash
+
+   $ elabftw-list Liam
+   163: test fake experiment without json metadata (Liam Keegan, 2021-10-07)
+   156: test fake experiment with json metadata (Liam Keegan, 2021-10-01)

docs/index.rst

@@ -12,6 +12,9 @@ A Python library for interacting with `eLabFTW <https://www.elabftw.net/>`_ expe
    :caption: Contents
 
    install
+   cli
+   python
+   source
 
 API Reference
 -------------

docs/install.rst

@@ -5,13 +5,13 @@ To install using pip:
 
 .. code-block:: bash
 
-    python -m pip install git+https://github.com/ssciwr/mease-elabftw
+   pip install mease-elabftw
 
 You also need to generate an API key in eLabFTW (User Panel -> API Keys -> GENERATE AN API KEY),
-and then set the environment variable `ELABFTW_TOKEN` to this key, e.g.
+and then set the environment variable ``ELABFTW_TOKEN`` to this key, e.g.
 
 .. code-block:: bash
 
-    export ELABFTW_TOKEN=abc123abc123abc123
+   export ELABFTW_TOKEN=abc123abc123abc123
 
 This key is needed to authenticate requests to the eLabFTW server.

docs/python.rst

@@ -0,0 +1,47 @@
+Python Interface
+================
+
+To import the library:
+
+.. code-block:: python
+
+   >>> import mease_elabftw
+
+
+Listing experiments
+-------------------
+
+To get a list of the experiments belong to user "Liam":
+
+.. code-block:: python
+
+   >>> import mease_elabftw
+   >>> from pprint import pprint
+   >>> pprint(mease_elabftw.list_experiments("Liam"))
+   ['163: test fake experiment without json metadata (Liam Keegan, 2021-10-07)',
+    '156: test fake experiment with json metadata (Liam Keegan, 2021-10-01)']
+
+
+NWB metadata
+------------
+
+To get a dict of the NWB metadata of the experiment with id ``156``:
+
+.. code-block:: python
+
+   >>> import mease_elabftw
+   >>> metadata = mease_elabftw.get_nwb_metadata(156)
+   >>> metadata["NWBFile"]["session_description"]
+   test fake experiment with json metadata
+   >>> metadata["NWBFile"]["identifier"]
+   20211001-8b6f100d66f4312d539c52620f79d6a503c1e2d1
+
+Upload a file
+-------------
+
+To upload the file "results.csv" to the experiment with id ``156``:
+
+.. code-block:: python
+
+   >>> import mease_elabftw
+   mease_elabftw.upload_file(156, "results.csv")

docs/source.rst

@@ -0,0 +1,5 @@
+Source code
+===========
+
+- Source code: `github.com/ssciwr/mease-elabftw <https://github.com/ssciwr/mease-elabftw/>`_
+- License: `MIT <https://raw.githubusercontent.com/ssciwr/mease-elabftw/main/LICENSE>`_

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name="mease_elabftw",
-    version="0.0.4",
+    version="0.0.5",
     author="Liam Keegan",
     author_email="[email protected]",
     description="Extracts metadata from eLabFTW experiments",