DOC: Setting up the configuration.

Mostly taken from the now deprecated wiki.

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

src/doc/concepts.rst

@@ -2,5 +2,5 @@
 The concepts of pycaosdb
 ========================
 
-Some text...
+- `Configuration <configuration>`
 

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'

src/doc/configuration.md

+# 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

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).

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>