Documentation: Added .css File, Changes to Chapter Structure/Hierachy…

… & Link formatting

This removes the previous work-arround for bold links and replaces it with a .css file.

The hierachy of different subsections has been altered to improve display in the sidebar.

Documentation/gh-pages/source/_static/css/custom.css

@@ -0,0 +1,3 @@
+a {
+  font-weight: bold;
+}

Documentation/gh-pages/source/contact.rst

@@ -30,10 +30,9 @@ Please register for the `mailing list <https://www.lists.kit.edu/sympa/subscribe
 References and Citation
 ==========
 
-**Cite** |our paper|_\ **:**
+**Cite** `our paper`_ **:**
+
 
-.. |our paper| replace:: **our paper**
-.. _our paper: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950
 
 .. code-block:: bash
 
@@ -44,11 +43,11 @@ References and Citation
     :width: 100%
     :height: 800px
 
-|
 
 In addition to this user guide, *Kassiopeia* and its associated libraries have been documented extensively in several
 PhD theses. Many of these can be found under the list of KATRIN publications_.
 
 
 
-.. _publications: https://www.katrin.kit.edu/375.php
+.. _publications: https://www.katrin.kit.edu/375.php
+.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950

Documentation/gh-pages/source/directory_structure.rst

@@ -0,0 +1,57 @@
+Directory structure and environmental variables
+===============================================
+
+After the compilation is completed and *Kassiopeia* has been installed to the installation directory, it is useful to
+set up some environment variables that allow you ton run ``Kassiopeia`` and other commands from any location. A script
+is provided that provides a similar functionality to the ``thisroot.sh`` script explained above. To set up *Kassiopeia*
+with the script, copy the following lines to your ``~/.bashrc`` (or similar), then logout and login again:
+
+.. code-block:: bash
+
+    #Set up the Kassiopeia environmental variables
+    source ~/kassiopeia/install/bin/kasperenv.sh
+
+The script will define a few environment variables that can be used outside of *Kassiopeia*:
+
+- KASPERSYS - the location of *Kassiopeia* binaries, libraries and configuration files.
+- KEMFIELD_CACHE - the location of the *KEMField* cache directory
+- KASPER_SOURCE - the location of the *Kassiopeia* source directory
+- KASPER_INSTALL - the location of the *Kassiopeia* installation directory
+
+The ``KASPERSYS`` and ``KEMFIELD_CACHE`` can, in principle, be changed to different locations before running
+simulations. This is intended to allow more flexible configurations on multi-user systems, or when multiple independent
+instances of the *Kassiopeia* software are installed. For the typical user, the variables can be left as they are.
+
+
+The complete set of *Kassiopiea* executables and configuration files will be found in the specified
+installation directory. The installation directory is broken down into several components, these are:
+
+- bin
+- cache
+- config
+- data
+- doc
+- include
+- lib
+- log
+- output
+- scratch
+
+The *Kassiopeia* executable can be found under the ``bin`` directory. Also in this directory is the script
+``kasperenv.sh`` that was mentioned above.
+
+The ``bin`` directory also contains other executables useful for interacting with the sub-components of *Kassiopeia*
+such as the *KEMField* or *KGeoBag* libraries. This included tools for generating particles without running a full
+simulation, for calculating electromagnetic fields, or for visualizing the simulation geometry.
+
+The ``lib`` directory contains all of the compiled libraries, as well as cmake and pkgconfig modules to enable linking
+against *Kassiopeia* by external programs. The ``include`` directory contains all of the header files of the compiled
+programs and libraries.
+
+The other directories: ``cache``, ``config``, ``data``, ``doc``, ``log``, ``output``, and ``scratch`` are all further
+sub-divided into parts which relate to each sub-module of the code: *Kassiopeia*, *Kommon*, *KGeoBag*, or *KEMField*.
+The ``cache`` and ``scratch`` directories are responsible for storing temporary files needed during run time for later
+reuse. The ``data`` directory contains raw data distributed with *Kassiopeia* needed for certain calculations (e.g.
+molecular hydrogen scattering cross sections). The ``log`` directory provides space to collect logging output from
+simulations, while the ``output`` directory is where simulation output is saved, unless otherwise specified.
+

Documentation/gh-pages/source/index.rst

@@ -45,44 +45,54 @@ Welcome to Kassiopeia's documentation!
     License <linktolicense.rst>
     Authors <authors.rst>
 
+
  .. toctree::
     :maxdepth: 4
-    :caption: User Guide 
+    :caption: Getting Started
 
     Introduction <introduction.rst> 
-    Getting Started <compiling.rst>
-    Examples and Tests <examples.rst>
-    Configuring Your Own Simulation <configuration.rst>
+    Setup with container <setup_container.rst>
+    Manual installation <setup_manual.rst>
+    Directory structure & environmental variables <directory_structure.rst>
+
+
+ .. toctree::
+    :maxdepth: 4
+    :caption: Usage
+
+    Running Kassiopeia <runningKassiopeia.rst>
+    Example configurations <examples.rst>
+    Configuring your own simulation <configuring_simulation.rst>
+
+
+ .. toctree::
+    :maxdepth: 4
+    :caption: Further Information
+
     Basic KGeoBag Shapes <kgeobag_basic.rst>
     Complex KGeoBag Shapes <kgeobag_complex.rst>
     Understanding Simulation Output <output.rst>
-
     Additional Simulation Tools <tools.rst>
     Visualization Techniques <visualization.rst>
     XML Bindings <bindings.rst>
     KEMField <KEMField_manual_link.rst>
 
 
 
-
-
-
-
-
 This simulation package by `the KATRIN collaboration`_ allows to run highly customizable particle tracking simulations
 along with calculations of electric and magnetic fields.
 
-.. _`the KATRIN collaboration`: https://katrin.kit.edu
+
 
 **Source Code:** https://github.com/KATRIN-Experiment/Kassiopeia
 
 
-**Quick start:** |Try it out online|_
+**Quick start:** `Try it out online`_
 in an interactive Binder session. Open a "VNC (Desktop)" tab and a terminal tab and run
 
 
-.. |Try it out online| replace:: **Try it out online**
-.. _Try it out online: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD
+
+
 
 
 .. code-block:: bash
@@ -92,10 +102,8 @@ in an interactive Binder session. Open a "VNC (Desktop)" tab and a terminal tab
 
 to run your first simulation! *Note: A VTK error indicates that the "VNC (Desktop)" tab is not open yet.*
 
-**Cite** |our paper|_\ **:**
+**Cite** `our paper`_ **:**
 
-.. |our paper| replace:: **our paper**
-.. _our paper: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950
 
 .. code-block:: bash
 
@@ -113,10 +121,13 @@ PhD theses. Many of these can be found under the list of KATRIN publications_.
 The `kassiopeia/full` image comes with a JupyterLab installation, can run on Kubernetes based JupyterHubs and is also used for the "try it out online" link above.
 
 
-|More information|_
+`More information`_
 
-.. |More information| replace:: **More information**
-.. _More information: https://github.com/KATRIN-Experiment/Kassiopeia/blob/main/Docker/README.md
+
+.. _`Try it out online`: https://mybinder.org/v2/gh/KATRIN-Experiment/KassiopeiaBinder/HEAD
+.. _`the KATRIN collaboration`: https://katrin.kit.edu
+.. _`our paper`: https://iopscience.iop.org/article/10.1088/1367-2630/aa6950
+.. _`More information`: https://github.com/KATRIN-Experiment/Kassiopeia/blob/main/Docker/README.md
 .. _publications: https://www.katrin.kit.edu/375.php
 
 

Documentation/gh-pages/source/introduction.rst

@@ -13,6 +13,7 @@ gases and offers specialized treatment of electron transport in silicon baseddet
     :local:
     :depth: 2
 
+
 The Kasper framework
 ====================
 
@@ -31,6 +32,7 @@ The *Kassiopeia* software relies upon three separate, but concurrently distribut
   constructing field maps for fast evaluation. *Kassiopeia* incorporates these three libraries in order to solve the
   equation of motion of a particle and deal with any stochastic interactions to which it might be subjected.
 
+
 Extending Functionality
 =======================
 
@@ -44,4 +46,24 @@ certain specific features in their own novel applications. Code contributions th
 can be submitted through GitHub and are always welcome.
 
 
-.. _KATRIN: https://www.katrin.kit.edu
+
+
+
+Supported operating systems and hardware requirements
+=====================================================
+
+*Kassiopeia* is supported and intended to run on systems running either Linux or MacOS X. Currently, it has been
+compiled and tested to run on fresh installations of the Linux distributions Fedora 31 and Ubuntu 20.04 LTS. It is also
+expected to compile and run on other Linux distributions, however this has not been tested, and the steps needed to
+compile *Kassiopeia* may deviate from what is outlined here.
+
+For minimal functionality and the ability to run the included example programs and simulations the following
+computer specifications or better are recommended:
+
+- Architecture: x86-64
+- CPU: Intel Core i3 @ 2.0 GHz
+- RAM: 4 GB
+- Free Disk Space: 10 GB
+
+
+.. _KATRIN: https://www.katrin.kit.edu

Documentation/gh-pages/source/runningKassiopeia.rst

@@ -0,0 +1,71 @@
+
+
+
+
+
+
+
+
+
+
+Running Kassiopeia
+==================
+
+
+After installation, and assuming the proper environmental variables have been set by running the script
+``kasperenv.sh``, *Kassiopeia* can be run directly from the command prompt. The script sets the environment variables
+accordingly so that the variable ``KASPERSYS`` points to the installation directory, and *Kassiopeia* can be found
+in the standard executable path. To run a *Kassiopeia* simulation, the usage is simply:
+
+.. code-block:: bash
+
+    Kassiopeia <path-to-xml-config-file>
+
+*Kassiopeia* also includes advanced variable replacement functionality, which makes it easy to modify one or many
+*simulation parameters on-the-fly. This can be done with the following usage:
+
+.. code-block:: bash
+
+    Kassiopeia <path-to-xml-config-file> -r <variable1>=<value1> <variable2>=<value2>
+
+In this case, all elements after the ``-r`` flag are considered variable definitions. Alternatively, the following
+syntax can be used. Here all variable names are prefixed with ``--``, and options can be freely mixed:
+
+.. code-block:: bash
+
+    Kassiopeia <path-to-xml-config-file> --<variable1>=<value1> --<variable2>=<value2>
+
+Verbosity levels
+----------------
+
+As a quick means to change the output verbosity (i.e. the amount of messages shown on the terminal while the program
+is running), the ``-v`` and ``-q`` flags can be used. Each option raises/lowers the verbosity level, so that the
+following example would raise the level by one unit. Try it with one of the example XML files below!
+
+.. code-block:: bash
+
+    Kassiopeia <path-to-xml-config-file> -v -q -v
+
+Output files
+------------
+
+Upon completion of a simulation, the ROOT output files may be found in the directory
+``<kassiopeia-install-path>/output/Kassiopeia`` (where ``<kassiopeia-install-path>`` usually can be replaced by
+``$KASPERSYS``.) These output files can then be processed or analyzed by an external program, such as ``root``. If
+VTK_ was enabled at build time and the corresponding writer was enabled in the XML file, a set of ``.vtp`` output files
+(polygon data in the VTK file format) is created in the same directory.
+
+In order to prematurely terminate a running simulation, *Kassiopeia* provides a user interrupt feature. To terminate the
+simulation while allowing *Kassiopeia* to clean up and save the accumulated data to file, the user may type ``Crtl-C``
+just once in the terminal. To immediately exit the simulation (without cleaning up or saving data), the user may press
+the key combination ``Crtl-C`` again, which leads to program termination.
+
+
+.. _VTK: http://www.vtk.org/
+.. _Paraview: http://www.paraview.org/
+.. _TBrowser: https://root.cern.ch/doc/master/classTBrowser.html
+.. _PyROOT: https://root.cern/manual/python/
+.. _uproot: https://pypi.org/project/uproot/
+.. _STL: https://en.wikipedia.org/wiki/STL_%28file_format%29
+
+.. [*] D. Furse *et al.* (2017) New J. Phys. **19** 053012, `doi:10.1088/1367-2630/aa6950 <https://doi.org/10.1088/1367-2630/aa6950>`_