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
 # 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
 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.
 
 $ 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')
 ```python
 >>> import graph
 >>> gc = graph.Connection('tls://graph.example.com:4439', 'graph.crt')


@@ -48,16 +62,17 @@ attribut: <p>Allgemeines Merkmal</p>
 ```
 
 ## Test script
 ```
 
 ## 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,
 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
 
 ## Plans

-

 Up to now, only a raw connection is implemented,
 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.
 
 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.