From 9031aa02ef781108e4960e63f4d02c558c16ba7c Mon Sep 17 00:00:00 2001
From: Daniel <daniel@harvey>
Date: Thu, 10 Dec 2020 12:33:40 +0100
Subject: [PATCH] DOC: Setting up the configuration.
Mostly taken from the now deprecated wiki.
---
src/caosdb/__init__.py | 6 ++++-
src/doc/concepts.rst | 2 +-
src/doc/conf.py | 5 ----
src/doc/configuration.md | 53 ++++++++++++++++++++++++++++++++++++++
src/doc/getting_started.md | 40 +++++++++++++++++++++++++---
src/doc/index.rst | 1 +
6 files changed, 97 insertions(+), 10 deletions(-)
create mode 100644 src/doc/configuration.md
diff --git a/src/caosdb/__init__.py b/src/caosdb/__init__.py
index 1989080f..b83442f1 100644
--- a/src/caosdb/__init__.py
+++ b/src/caosdb/__init__.py
@@ -22,7 +22,11 @@
# ** end header
#
-"""CaosDB Python bindings
+"""CaosDB Python bindings.
+
+Tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or alternatively
+in `~/.pycaosdb.ini` upon import. After that, the ini file `pycaosdb.ini` in the current working
+directory will be read additionally, if it exists.
"""
from os import environ, getcwd
diff --git a/src/doc/concepts.rst b/src/doc/concepts.rst
index 23e5fc4f..fb7f3a62 100644
--- a/src/doc/concepts.rst
+++ b/src/doc/concepts.rst
@@ -2,5 +2,5 @@
The concepts of pycaosdb
========================
-Some text...
+- `Configuration <configuration>`
diff --git a/src/doc/conf.py b/src/doc/conf.py
index b8f00c81..4264eba3 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -55,11 +55,6 @@ templates_path = ['_templates']
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
-# source_suffix = {
-# '.rst': 'restructuredtext',
-# '.md': 'markdown',
-# }
-
# The master toctree document.
master_doc = 'index'
diff --git a/src/doc/configuration.md b/src/doc/configuration.md
new file mode 100644
index 00000000..bf900f0c
--- /dev/null
+++ b/src/doc/configuration.md
@@ -0,0 +1,53 @@
+# Configuration of pycaosdb #
+
+The behavior of pycaosdb is defined via the [configuration](https://caosdb.gitlab.io/caosdb-pylib/_apidoc/caosdb.html#module-caosdb.configuration) module, initial values are taken from
+the configuration files.
+
+Pycaosdb tries to read from the inifile specified in the environment variable `PYCAOSDBINI` or
+alternatively in `~/.pycaosdb.ini` upon import. After that, the ini file `pycaosdb.ini` in the
+current working directory will be read additionally, if it exists.
+
+## Authentication ##
+
+The default configuration (that your are asked for your password when ever a connection is created
+can be changed by setting `password_method`:
+
+* with `password_method=input` password (and possibly user) will be queried on demand (**default**)
+* use the password manager [pass](https://www.passwordstore.org) by using `pass` as value, see also the [ArchWiki
+ entry](https://wiki.archlinux.org/index.php/Pass#Basic_usage). This also requires ```password_identifier``` which refers to the identifier within pass
+ for the desired password.
+* install the python package [keyring](https://pypi.org/project/keyring), to use the system keychain/wallet (macOS, GNOME, KDE,
+ Windows). The password will be queried on first usage.
+* with `password_method=plain` (**strongly discouraged**)
+
+```ini
+[Connection]
+username=YOUR_USERNAME
+
+# password using "pass" password manager
+#password_method=pass
+#password_identifier=...
+
+# using the system keyring/wallet (macOS, GNOME, KDE, Windows)
+#password_method=keyring
+
+#discouraged: password in plain text
+#password_method=plain
+#password=YOUR_PASSWORD
+```
+
+## SSL Certificate ##
+
+You can set the pass to the ssl certificate to be used:
+
+```ini
+[Connection]
+cacert=/path/to/caosdb.ca.pem
+```
+
+## Further Settings ##
+
+`debug=0` ensures that debug information is **not** printed to the terminal every time you interact
+with CaosDB which makes the experience much less verbose. Set it to 1 or 2 in case you want to help
+debugging (which I hope will not be necessary for this tutorial) or if you want to learn more about
+the internals of the procotol
diff --git a/src/doc/getting_started.md b/src/doc/getting_started.md
index b13f46d8..68dcf612 100644
--- a/src/doc/getting_started.md
+++ b/src/doc/getting_started.md
@@ -13,12 +13,46 @@ typically be installed automatically):
### How to install ###
-To install pycaosdb locally, use `pip` (called `pip3` on some systems) in the top-level directory:
+To install pycaosdb locally, use `pip3` (also called `pip` on some systems):
```sh
+pip3 install --user caosdb
+```
+
+---
+
+Alternatively, obtain the sources from GitLab and install from there:
+
+```sh
+git clone https://gitlab.com/caosdb/caosdb-pylib
+cd caosdb-pylib
pip3 install --user .
```
-## - Install - import - enjoy ##
+## Configuration ##
+
+Download [the sample configuration file](https://gitlab.com/caosdb/caosdb-pylib/-/raw/dev/examples/pycaosdb.ini) and save it as `.pycaosdb.ini` in your home directory or
+as `pycaosdb.ini` in your current working directory.
+
+Now, change the url and username fields as required. (Ask your CaosDB administrator or IT crowd if
+you do not know what to put there, but for demo instances like https://demo.indiscale.com, `admin`
+and `caosdb` often works).
+
+More information about the configuration is available [in this documentation](configuration.html) as well.
+
+## Try it out ##
+
+Start Python and check whether the you can access the database. (You will be asked for the
+password):
+
+```python
+In [1]: import caosdb as db
+In [2]: db.Info()
+Please enter the password: # It's `caosdb` for the demo server.
+Out[2]: Connection to CaosDB with 501 Records.
+```
+
+Note: This setup will ask you for your password whenever a new connection is created. If you do not
+like this, check out the "Authentication" section in the [configuration documentation](configuration.html).
-*TODO, possibly copy from https://gitlab.com/caosdb/caosdb/-/wikis/manuals/pylib/Setting-up-caosdb-pylib*
+Now would be a good time to continue with the [tutorials](tutorials.html).
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 7e4c86ac..fe309753 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -9,6 +9,7 @@ Welcome to pycaosdb's documentation!
Getting started <getting_started>
Concepts <concepts>
+ Configuration <configuration>
tutorials
API documentation<_apidoc/modules>
--
GitLab