docs: Convert Knora base ontology doc to RST. (#289)

* docs: Convert Knora base ontology doc to RST.

* fix (nest inline formatting): Use raw HTML

* docs: Clean up after review of #289.

docs/Readme.md

@@ -2,12 +2,13 @@
 
 ## 1 Install Python 3 ##
 
+On Mac OS X:
+
 ```
 $ brew install python3
 ```
 
-or get the install package from: https://www.python.org
-
+On Linux, use your distribution's package manager, or see [the Python web site](https://www.python.org).
 
 ## 2 Installing Sphinx ##
 
@@ -23,21 +24,30 @@ To create your own environment, run inside the docs folder:
 ```
 $ python3 -m venv env
 ```
->**Remark for Anaconda users on Mac OS and Linux**
+
+**Remark for Anaconda users on Mac OS and Linux**
+
 Anaconda3/2 for Linux and Mac OS do not have ensurepip installed.
-So instead of running pyvenv env, you can first run pyvenv env --without-pip, then download the get-pip.py from [pip's homepage](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py), and install the pip in activated env venv.   
+So instead of running pyvenv env, you can first run pyvenv env --without-pip, then download the get-pip.py from [pip's homepage](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py), and install the pip in activated env venv.
+
 To create virtual environment without pip, run inside  doc folder:
-   ```
-    $ pyvenv env --without-pip
-   ```
+
+```
+$ pyvenv env --without-pip
+```
+
 Activating the env:
-   ```
-    $ source ./env/bin/activate
-   ```
+
+```
+$ source ./env/bin/activate
+```
+
 Install pip in your venv, run inside the env folder:
-   ```
-    $ python ~/Downloads/get-pip.py
-   ```
+
+```
+$ python ~/Downloads/get-pip.py
+```
+
 Now you can continue with pip commands below   
 
 Then, each developer will set up their own virtualenv and run:
@@ -58,9 +68,19 @@ To generate a "requirements" file (usually requirements.txt), that you commit wi
 $ ./env/bin/pip freeze > requirements.txt
 ```
 
-## 3 Generating Documentation ##
+## 3 Install Graphviz ##
+
+You will need [Graphviz](http://www.graphviz.org/). On Mac OS X:
+
+```
+$ brew install graphviz
+```
+
+On Linux, use your distribution's package manager.
+
+## 4 Generating Documentation ##
 
-### 3.1 Bulding the Documentation ###
+### 4.1 Bulding the Documentation ###
 
 Inside the docs folder type for the html documentation type
 
@@ -80,7 +100,7 @@ few times, so that the index is properly generated.
 
 The generated documentation can be found under  ```_build/latex```
 
-### 3.2 Problems with Locales ###
+### 4.2 Problems with Locales ###
 
 Error message when trying to generate the documentation:
 
@@ -95,9 +115,9 @@ export LC_ALL=de_CH.UTF-8
 export LANG=de_CH.UTF-8
 ```
 
-## 4 Documentation of the Knora JSON API V1 Request and Response Format
+## 5 Documentation of the Knora JSON API V1 Request and Response Format
 
-### 4.1 Requirements
+### 5.1 Requirements
 
 The JSON request and response format is formally described using typescript interfaces. To create the docuemntation from these interfaces, we use `typedoc`.
 
@@ -109,7 +129,7 @@ npm install --global typedoc
 
 If you do not have `npm` (node package manager), install it first. You will find more information about `npm` here: <https://www.npmjs.com/>.
 
-### 4.2 Building the Documentation
+### 5.2 Building the Documentation
 
 Inside the docs folder type for the html documentation type
 

docs/conf.py

@@ -31,6 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
+    'sphinx.ext.graphviz'
 ]
 
 # Add any paths that contain templates here, relative to this directory.