Add initial content to the Sphinx Doc

docs/source/advanced/cmake.rst

@@ -0,0 +1,2 @@
+CMake Arguments
+===============

docs/source/basic/algorithm.rst

@@ -0,0 +1,2 @@
+Algorithm
+=========

docs/source/basic/installation.rst

@@ -0,0 +1,91 @@
+Installation
+============
+
+Vikunja builds and installs itself using `CMake <https://cmake.org/>`_. Before you can install and use vikunja, you have to install the only dependency `alpaka <https://github.com/alpaka-group/alpaka>`_. Vikunja supports alpaka from version 0.6 until 0.8. It is recommend to use the latest alpaka version. Alpaka itself has also a single dependency, boost. Read the `alpaka documentation <https://github.com/alpaka-group/alpaka#dependencies>`_ to determine the supported boost version.
+
+.. code-block:: bash
+
+  # assumed alpaka is installed via `cmake --install .` on a location, where cmake can find it
+  # git clone https://github.com/alpaka-group/vikunja.git
+  cd vikunja
+  mkdir build && cd build
+  cmake ..
+  cmake --build .
+  cmake --install .
+
+Build Tests and Examples
+------------------------
+
+Enable and run the tests:
+
+.. code-block:: bash
+
+   # start in the vikunja project folder
+   mkdir build && cd build
+   cmake .. -DBUILD_TESTING=ON
+   cmake --build .
+   ctest
+
+Enable and run an example:
+
+.. code-block:: bash
+
+   # start in the vikunja project folder
+   mkdir build && cd build
+   cmake .. -DVIKUNJA_BUILD_EXAMPLES=ON
+   cmake --build .
+   ./example/transform/example_transform
+
+
+Use vikunja in a CMake project via ``find_package``
+---------------------------------------------------
+
+Once vikunja and alpaka are successfully installed, you can use them in your project via the cmake function ``find_packge``.
+
+.. code-block:: cmake
+
+   cmake_minimum_required(VERSION 3.18)
+   project(vikunjaProject)
+
+   find_package(vikunja REQUIRED)
+
+   alpaka_add_executable(${CMAKE_PROJECT_NAME} main.cpp)
+   target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE vikunja::vikunja)
+
+At the cmake configuration time of your project, you need to enable at least on alpaka accelerator to execute a vikunja function on a processor. The accelerators are enabled via the cmake argument``-DALPAKA_ACC_<...>_ENABLE=ON``. All existing accelerators can be found `here <https://alpaka.readthedocs.io/en/latest/advanced/cmake.html>`_.
+
+.. code-block:: bash
+
+   # start in the folder of the root CMakeLists.txt
+   mkdir build && cd build
+   # enable serial CPU and CUDA GPU accelerator
+   cmake .. -DALPAKA_ACC_CPU_B_SEQ_T_SEQ_ENABLE=ON -DALPAKA_ACC_GPU_CUDA_ENABLE=ON
+   cmake --build .
+
+By default ``find_package(vikunja)`` runs ``find_package(alpaka)``, if the ``alpaka::alpaka`` target is not already defined.
+
+Use vikunja in a CMake project via ``add_subdirectory``
+-------------------------------------------------------
+
+Vikunja also provides cmake integration via ``add_subdirectory``. The `add_subdirectory <https://cmake.org/cmake/help/latest/command/add_subdirectory.html>`_ approach does not require vikunja or alpaka to be installed and allows for easy deployment of a custom vikunja version together with your project.
+
+.. code-block:: cmake
+
+   cmake_minimum_required(VERSION 3.18)
+   project(vikunjaProject)
+
+   add_subdirectory(alpaka REQUIRED)
+   add_subdirectory(vikunja REQUIRED)
+
+   alpaka_add_executable(${CMAKE_PROJECT_NAME} main.cpp)
+   target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE vikunja::vikunja)
+
+.. code-block:: bash
+
+   # start in the folder of the root CMakeLists.txt
+   mkdir build && cd build
+   # enable OpenMP CPU backend
+   cmake .. -DALPAKA_ACC_CPU_B_SEQ_T_OMP2_ENABLE=ON
+   cmake --build .
+
+It is also supported to mix the ``find_package`` and ``add_subdirectory`` approaches for vikunja and alpaka.

docs/source/basic/introduction.rst

@@ -0,0 +1,18 @@
+Introduction
+============
+
+The basic concept of vikunja is to run an ``algorithm`` with an ``operator`` over a range of elements.
+
+* The ``algorithm`` specifies how the elements of one ore more input ranges are accessed and what kind of operator is applied on it. The algorithm also determines the shape of the result. Examples are:
+
+  * **Tranform**: Takes a range of elements as input and returns a range of the same size. **Transform** applies an operator on each element of the input range.
+  * **Reduce**: Takes a range of elements as input and returns a single element. The reduce operator takes two elements of the input range, applies an operation to them, and returns a single element. The operator is applied up to the point where only one element remains.
+  * For more examples see: :ref:`Algorithm <Algorithm>`
+* An ``operator`` describes an algorithm which is applied to one (unary operator) or two (binary operator) elements and returns a result. The following examples assume that **i** is the first and **j** the second input element:
+
+  * **sum**: `return i+j;`
+  * **double of an element**: `return 2*i;`
+
+.. literalinclude:: ../../../example/transform/src/transform-main.cpp
+   :language: C++
+   :caption: transform-main.cpp

docs/source/conf.py

@@ -31,6 +31,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autosectionlabel'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -49,7 +50,12 @@
 #
 html_theme = 'sphinx_rtd_theme'
 
+html_logo = "logo/vikunja_logo.svg"
+html_theme_options = {
+    "logo_only"  : True
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']

docs/source/development/sphinx.rst

@@ -0,0 +1,2 @@
+Sphinx Doc
+==========

docs/source/index.rst

@@ -3,19 +3,40 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to vikunja's documentation!
+.. only:: html
+
+  .. image:: logo/vikunja_logo.svg
+     :width: 400
+
+.. only:: latex
+
+  .. image:: logo/vikunja_logo.pdf
+
+
+Vikunja is a performance portable algorithms library defines functions for a variety of purposes that operate on ranges of elements. It supports the execution on multi core CPUs and various GPUs.
+
+
+vikunja - How to Read This Document
 ===================================
 
-The documentation will follow. At the moment this empty shinxdoc exists to set up an automatic deployment on readthedocs.
+Generally, **follow the manual pages in-order** to get started. Individual chapters are based on the information of the chapters before. The documentation is separated in three sections. The ``basic`` section explains all concepts of vikunja. In the ``advanced`` you will get more details of certain functionalities. If you want to provide to the project, you should have a look in the ``development`` section.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Basic
+
+   basic/introduction.rst
+   basic/installation.rst
+   basic/algorithm.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced
 
+   advanced/cmake.rst
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
+   :caption: Development
 
-* :ref:`genindex`
-* :ref:`search`
+   development/sphinx.rst

docs/source/logo/README.md

@@ -0,0 +1 @@
+The Logo was created with Inkscape. The text uses the font `Latin Modern Sans Quotation` and the colors `005aa0ff` (blue - RGBA) and `f0781eff` (orange).