Add documentation

First draft of the readthedocs page for jpsreport (copied files from jpscore repo)

.gitignore

@@ -2,11 +2,9 @@
 /lib/
 /bin/
 /outside/
-/doc
 /Debug
 /Release
 /Testing
-/doc/html
 /figs
 /figs_bot
 /inputfiles

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx==4.2.0
+sphinx_rtd_theme==1.0.0
+readthedocs-sphinx-search==0.1.1
+myst-parser==0.17.0

docs/source/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'JPSreport'
+copyright = '2022, Forschungszentrum Juelich GmbH, IAS-7'
+author = 'JuPedSim Development Team'
+
+release = '0.9.4'
+version = '0.9.4'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'myst_parser',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+html_static_path = ['_static']
+html_logo = "images/jupedsim_small.png"
+
+html_theme_options = {
+    'navigation_depth': -1,
+    'logo_only': True,
+    'style_nav_header_background': 'white',
+    'collapse_navigation': False,
+    'titles_only': False
+}

docs/source/index.rst

@@ -0,0 +1,21 @@
+==============================================
+JPSreport
+==============================================
+|DOI|
+
+``JPSreport`` is a command line module to analyze trajectories of pedestrians.
+
+Analyze pedestrian trajectories
+===============================
+
+1. On how to install ``JPSreport`` on your machine look at: :ref:`Installing JPSreport<install>`
+2. If you have ``JPSreport`` installed see :ref:`Getting started with JPSreport<usage>` on how to configure the analysis.
+3. For a more detailed look at the provided analysis methods look at: :ref:`Measurement methods<methods>`
+
+.. |DOI| image:: https://zenodo.org/badge/109670242.svg
+   :target: https://zenodo.org/badge/latestdoi/109670242
+
+.. toctree::
+  install
+  usage
+  methods

docs/source/install.rst

@@ -0,0 +1,192 @@
+.. _install:
+====================
+Installing JPSreport
+====================
+
+Download installer
+==================
+
+Release
+-------
+
+- Windows installer:
+- MacOS installer:
+
+
+Nightly build
+-------------
+
+- Windows installer:
+- MacOS installer:
+
+
+Build from source
+=================
+It should be possible to build on all major platforms however, we only test a few:
+
+Right now, we ensure a working Build for:
+
+- Windows 10
+- MacOS BigSur
+- Ubuntu 20.04
+
+Get the code
+------------
+In order to compile JPSreport, you need to download the source code via:
+
+.. code:: bash
+
+   git clone https://github.com/JuPedSim/jpscore.git
+
+Build Options
+-------------
+We support only a few settings. For a list of build options, please see [CMakeLists.txt] directly.
+
+
+General Information
+-------------------
+All of the following descriptions assume the following layout on disk:
+
+::
+
+    .
+    ├── jpsreport <- code repository
+    ├── jpsreport-build <- build folder
+    └── jpsreport-deps <- install location of library dependencies
+
+
+Build on Windows
+----------------
+
+System Requirements
+^^^^^^^^^^^^^^^^^^^
+- Visual Studio
+- vcpkg (see https://vcpkg.io/en/getting-started.html)
+
+Library Dependencies
+^^^^^^^^^^^^^^^^^^^^
+On Windows dependencies are installed with ``vcpkg``, get it from vcpkg.io.
+``vcpkg`` will automatically download and install the dependencies listen in ``vcpkg.json`` if used with CMake.
+
+
+Compiling
+^^^^^^^^^
+To call the CMake configuration and to install the needed dependencies, call
+
+.. code:: bash
+
+    cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=<PATH-TO-VCPKG-INSTALLATION>/scripts/buildsystems/vcpkg.cmake <path-to-cmakelists>
+
+
+To finally compile the source code, use
+
+.. code:: bash
+
+    cmake --build . --config Debug
+
+
+Build on Linux
+----------------
+
+System Requirements
+^^^^^^^^^^^^^^^^^^^
+
+Builds are only tested on the latest Ubuntu LTS version (at this time 20.04).
+To compile from source you will need a couple of system dependencies.
+
+- C++17 capable compiler (default GCC will do)
+- wget
+
+Recommended:
+
+- ninja
+
+Library Dependencies
+^^^^^^^^^^^^^^^^^^^^
+On Linux and MacOS all dependencies are built from source, they are either part of the source tree and do not need any special attention or they are built with ``scripts/setup-deps.sh``.
+To compile dependencies invoke the script and specify the install path:
+
+.. code:: bash
+
+    ./scripts/setup-deps.sh --install-path ~/jpsreport-deps
+
+
+The output created in ``~jpsreport-deps`` now contains an install tree of all required library dependencies.
+
+.. warning::
+    If you do not specify an install path the script tries to install into ``/usr/local``.
+
+Compiling
+^^^^^^^^^
+Now that you have all library dependencies, you need to generate build files with CMake and compile.
+
+.. code:: bash
+
+   mkdir jpsreport-build
+   cd jpsreport-build
+   cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=<path-to-dependencies> <path-to-cmakelists>
+   ninja
+
+Alternatively you can generate a make based build with:
+
+.. code:: bash
+
+   mkdir jpsreport-build
+   cd jpsreport-build
+   cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=<path-to-dependencies> <path-to-cmakelists>
+   make -j$(nproc)
+
+You will find the ``jpsreport`` executable in ``jpsreport-build/bin`` after the build.
+
+Build on MacOS
+----------------
+
+System Requirements
+^^^^^^^^^^^^^^^^^^^
+
+- AppleClang/XCode command line tools
+- wget
+
+Recommended:
+
+- ninja
+
+Library Dependencies
+^^^^^^^^^^^^^^^^^^^^
+
+On Linux and MacOS all dependencies are built from source, they are either part of the source tree and do not need any special attention or they are built with ``scripts/setup-deps.sh``.
+To compile dependencies invoke the script and specify the install path:
+
+.. code:: bash
+
+    ./scripts/setup-deps.sh --install-path ~/jpsreport-deps
+
+
+The output created in ``~jpsreport-deps`` now contains an install tree of all required library dependencies.
+
+.. warning::
+    If you do not specify an install path the script tries to install into ``/usr/local``.
+
+
+Compiling
+^^^^^^^^^
+
+Now that you have all library dependencies, you need to generate build files with CMake and compile.
+
+.. code:: bash
+
+   mkdir jpsreport-build
+   cd jpsreport-build
+   cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=<path-to-dependencies> <path-to-cmakelists>
+   ninja
+
+Alternatively you can generate a make based build with:
+
+.. code:: bash
+
+   mkdir jpsreport-build
+   cd jpsreport-build
+   cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=<path-to-dependencies> <path-to-cmakelists>
+   make -j$(nproc)
+
+You will find the ``jpsreport`` executable in ``jpsreport-build/bin`` after the build.