Add some clarifications to documentation

* Where to find the correct certificate chain and key file
* Optionally using a virtual environment to encapsulate dependency
  installation
* Some additions to .gitignore to have cleaner statuses

diff --git a/.gitignore b/.gitignore
index e0bb05d6c8de80ddc6fd1cd39081ddc9e01c68c5..badcbcef7161839812a275c6fa2dab56bbc9c10b 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
-graph.crt
-config.json
-*-briefbogen.pdf
+/venv/
+/graph_graphit.egg-info/
+/graph.crt
+/config.json
+/*-briefbogen.pdf
+__pycache__/

diff --git a/doc/index.md b/doc/index.md
index e3f6bca750f61a5f27bb880b166a025511df2c4f..f2dd065db3deb9ea05b004705c25288a78e746c3 100644 (file)
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,25 +1,39 @@
 # Python Graph API
-
 This is a minimal Python API for the [Graph](https://graph-it.com/).
 It works with Python 2 as well as Python 3.
 
 ## Installation
+Optionally, create and activate a virtual environment, so that
+installations are not system-wide:
+```shellsession
+$ python -m venv <path to venv>
+$ source <path to venv>/bin/activate
+```
 
-The Python Graph API can be installed with `pip` directly from our git repository:
-```sh
+The Python Graph API can be installed with `pip` directly from our git
+repository:
+```shellsession
 $ pip install git+git://git.graph-it.com/graphit/graph-client-py.git
 ```
 
 The Graph API uses [msgpack](https://msgpack.org/).
 So, the Python binding for it will be installed as a dependency.
 
-In order to use TLS connections to graphs, a client certificate chain has to
-be available in a file.
+In order to use TLS connections to graphs, a client certificate chain
+including the private key has to be available in a file.
+(Internally,
+[`SSLContext.load_cert_chain()`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_cert_chain)
+is used to establish the TLS connection.)
 
-## Usage
+In our current graph installations a chain file with a private key can be
+found in `/var/lib/graph/var/cert/srv/local.srv.pem`:
+```shellsession
+$ scp graph.example.com:/var/lib/graph/var/cert/srv/local.srv.pem graph.crt
+```
 
-A graph connection is initialised by giving a URL and optionally the filename
-of the certificate chain to the constructor:
+## Usage
+A graph connection is initialised by giving a URL and (if it is a TLS URL)
+the filename of the certificate chain to the constructor:
 ```python
 >>> import graph
 >>> gc = graph.Connection('tls://graph.example.com:4439', 'graph.crt')
@@ -48,16 +62,17 @@ attribut: <p>Allgemeines Merkmal</p>
 ```
 
 ## Test script
-
 The `test.py` script reads the configuration of a main graph from
 `config.json`, queries this main graph for remote graphs configured in it,
-prints a summary of all graph modules in the main graph and all remote graphs
-and downloads stationeries in all the graphs if they are configured there.
+prints a summary of all graph modules in the main graph and all remote
+graphs and downloads stationeries in all the graphs if they are configured
+there.
 
 ## Plans
-
 Up to now, only a raw connection is implemented,
-i.e., the Python implementation does not know anything about the actual API calls and just passes them to the graph server.
+i.e., the Python implementation does not know anything about the actual API
+calls and just passes them to the graph server.
 
 We should add implementation and documentation for these actual API calls.
-This would also allow to do at least some of the necessary conversions already in the library.
+This would also allow to do at least some of the necessary conversions
+already in the library.