added also a short doc how to run sphinx rendering locally

doc/Testing-Sphinx-based-Rendering.md

@@ -0,0 +1,112 @@
+
+# How to Check if Sphinx-based Rendering of `tobac` is Working?
+
+
+The workflow has been tested in a linux system. We aim to build a static website out of the documentation material present in `tobac`.
+
+
+## 1. Preparing the Local Environment
+
+* **choose a separate place for your testing**
+
+  I will use the temporary directory `/tmp/website-testing` which I need to create. You can use a dedicated place of your choice ...
+
+  ```bash
+  > mkdir /tmp/website-testing
+  > cd /tmp/website-testing
+  ```
+  I will indicate my position now with the `/tmp/website-testing>` prompt.
+
+* **get the official repository**
+
+  ```bash
+  /tmp/website-testing> git clone https://github.com/tobac-project/tobac
+  ```
+
+  You might like to test a certain remote branch `<BRANCH>` then do:
+
+  ```bash
+  git fetch --all
+  git checkout -t origin/<BRANCH> 
+  ```
+
+* **Python environment**
+    * create a python virtual env
+        ```bash
+        /tmp/website-testing> python -m venv .python3-venv
+        ```
+
+    * and install requirements
+        ```bash
+        # deactivation conda is only necessary if your loaded conda before ...
+        /tmp/website-testing> conda deactivate
+
+        # activate the new env and upgrade `pip`
+        /tmp/website-testing> source .python3-venv/bin/activate
+        /tmp/website-testing> pip install --upgrade pip
+        
+        # now everything is installed into the local python env!
+        /tmp/website-testing> pip install -r tobac/doc/requirements.txt
+
+        # and also install RTD scheme
+        /tmp/website-testing> pip install sphinx_rtd_theme
+
+        ```
+        `pip`-based installation takes a bit of time, but is much faster than `conda`. If the installation runs without problems, you are ready to build the website.
+
+
+## 2. Building the Website
+
+Actually, only few steps are needed to build the website, i.e.
+
+
+* **running sphinx for rendering**
+
+    ```bash
+    /tmp/website-testing> cd tobac
+
+    /tmp/website-testing/tobac> sphinx-build -b html doc doc/_build/html
+    ```
+
+    If no severe error appeared
+
+
+* **view the HTML content**
+
+    ```bash
+    /tmp/website-testing/tobac> firefox doc/_build/html/index.html
+    ```
+
+
+## 3. Parsing Your Local Changes
+
+Now, we connect to your locally hosted `tobac` repository and your development branch.
+
+* **connect to your local repo**: 
+    Assume your repo is located at `/tmp/tobac-testing/tobac`, then add a new remote alias and fetch all content with
+
+    ```bash
+    /tmp/website-testing/tobac> git remote add local-repo /tmp/tobac-testing/tobac
+    /tmp/website-testing/tobac> git fetch --all
+    ```    
+* **check your development branch out**:
+    Now, assume the your development branch is called `my-devel`, then do
+
+    ```bash
+    # to get a first overview on available branches
+    /tmp/website-testing/tobac> git branch --all
+    
+    # and then actually get your development branch
+    /tmp/website-testing/tobac> git checkout -b my-devel local-repo/my-devel
+    ```
+
+    You should see your developments, now ...
+
+* **build and view website again**
+
+    ```bash    
+    /tmp/website-testing/tobac> sphinx-build -M clean doc doc/_build
+    /tmp/website-testing/tobac> sphinx-build -b html doc doc/_build/html
+    /tmp/website-testing/tobac> firefox _build/html/index.html
+    ```
+