Merge branch 'python' into 'master'

Merge python environment

See merge request !1

.coveragerc

+[run]
+source = km3buu
+
+[report]
+include =
+    km3buu/*
+omit =
+    */tests/*
+exclude_lines =
+    pragma: no cover
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if __name__ == .__main__.:
+    if self.debug:
+    if settings.DEBUG
+    def __repr__

.gitignore

@@ -4,3 +4,45 @@
 # GiBUU
 *.dat
 output/
+
+# Version info for PyPI
+km3buu/version.py
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.pyxbldc
+
+# Distribution / packaging
+.Python
+env/
+bin/
+build/
+develop-eggs/
+dist/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.eggs
+
+# venv, pyenv tmp
+.python-version
+venv
+
+# Sphinx documentation
+doc/_build/
+doc/auto_examples/
+doc/modules/
+doc/api
+
+# 
+junit*.xml
+reports
+

.gitlab-ci.yml

+image: docker.km3net.de/base/singularity-py3:3.5.3
+
 variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
     DOCKER_HOST: tcp://docker:2375
     DOCKER_DRIVER: overlay2
     CONTAINER_TEST_IMAGE: docker.km3net.de/simulation/km3buu:$CI_COMMIT_REF_SLUG
     CONTAINER_RELEASE_IMAGE: docker.km3net.de/simulation/km3buu:$CI_COMMIT_TAG
     CONTAINER_LATEST_IMAGE: docker.km3net.de/simulation/km3buu:latest
 
+cache:
+  paths:
+   - .cache/pip
+   - venv/
+   - GiBUU.simg
+  key: "$CI_COMMIT_REF_SLUG"
+
 stages:
+    - test
+    - coverage
     - docker
+    - reset_cache_image
     - release
+    - doc
+
+reset_test_image:
+    stage: reset_cache_image
+    cache:
+        paths:
+            - GiBUU.simg
+    script:
+        - rm GiBUU.simg
+    only:
+        - tags
+
+.virtualenv_template: &virtualenv_definition |
+  python -V
+  pip install virtualenv
+  virtualenv venv
+  source venv/bin/activate
+  pip install -U pip setuptools yapf
+  if [ ! -f GiBUU.simg ]; then make buildremote; fi
+  make install-dev
+  pip list
+
+.junit_template: &junit_definition
+    artifacts:
+      reports:
+        junit: "reports/junit*.xml"
+
+
+test:
+    image: docker.km3net.de/base/singularity-py3:3.5.3
+    stage: test
+    tags:
+        - docker
+    script:
+        - *virtualenv_definition
+        - make test
+    <<: *junit_definition
+
+code-style:
+    image: docker.km3net.de/base/singularity-py3:3.5.3
+    stage: test
+    script:
+        - *virtualenv_definition
+        - yapf -r -d -e "venv" ./km3buu
+    allow_failure: true
+
+coverage:
+    image: docker.km3net.de/base/singularity-py3:3.5.3
+    stage: coverage
+    tags:
+        - docker
+    script:
+        - *virtualenv_definition
+        - "make test-cov|grep TOTAL| awk '{printf \"COVERAGE: %.2f%%\", (1-$3/$2)*100 }'"
+    coverage: '/COVERAGE:\s*([0-9]*\.[0-9]*%)/'
+    #     - make test-cov
+    # coverage: '/TOTAL.+ ([0-9]{1,3}%)/'
+    artifacts:
+        paths:
+            - reports/coverage
+
 
 docker:
-   image: docker:stable
-   services:
-     - docker:dind
-   stage: docker
-   script:
-     - docker build --pull -t $CONTAINER_TEST_IMAGE .
-     - docker push $CONTAINER_TEST_IMAGE
-   tags:
-     - docker
-   only:
-     - tags
+  image: docker:stable
+  services:
+    - docker:dind
+  stage: docker
+  script:
+    - docker build --pull -t $CONTAINER_TEST_IMAGE .
+    - docker push $CONTAINER_TEST_IMAGE
+  tags:
+    - docker
+  only:
+    - tags
 
 release-image:
-   image: docker:stable
-   services:
-     - docker:dind
-   stage: release
-   script:
-     - docker pull $CONTAINER_TEST_IMAGE
-     - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
-     - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_LATEST_IMAGE
-     - docker push $CONTAINER_RELEASE_IMAGE
-     - docker push $CONTAINER_LATEST_IMAGE
-   tags:
-     - docker
-   only:
-     - tags
+  image: docker:stable
+  services:
+    - docker:dind
+  stage: release
+  script:
+    - docker pull $CONTAINER_TEST_IMAGE
+    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_RELEASE_IMAGE
+    - docker tag $CONTAINER_TEST_IMAGE $CONTAINER_LATEST_IMAGE
+    - docker push $CONTAINER_RELEASE_IMAGE
+    - docker push $CONTAINER_LATEST_IMAGE
+  tags:
+    - docker
+  only:
+    - tags
+
+pages:
+    image: docker.km3net.de/base/python:3.6
+    stage: doc
+    script:
+        - make install-dev
+        - cd doc && make clean && cd ..
+        - make doc
+        - mv doc/_build/html public/
+        - mv reports/coverage public/coverage
+    artifacts:
+        paths:
+            - public
+    cache: {}
+    only:
+        - tags
+        - master
+        - python
+
 

CHANGELOG.rst

+Unreleased changes
+------------------
+
+* None
+
+
+Version 0
+---------
+
+0.2.0 / 2020-02-08
+~~~~~~~~~~~~~~~~~~
+* Initial commit

CONTRIBUTING.md

+Contributing
+------------
+
+Do it!

Makefile

+PKGNAME=km3buu
+ALLNAMES = $(PKGNAME)
+
 export REPO_OUTPUT_DIR := output
 export REPO_JOBCARDS_DIR := jobcards
 export CONTAINER_OUTPUT_DIR := /opt/output
@@ -8,7 +11,6 @@ default: run
 build: km3buu.Singularity
 	sudo singularity build GiBUU.simg km3buu.Singularity 
 
-
 run: GiBUU.simg
 	@if [ ! -d "jobcards/${CARDSET}" ];then \
 	    exit 1; \
@@ -32,5 +34,29 @@ buildremote:
 
 clean:
 	@rm -rf output
+	python setup.py clean --all
+
+### PYTHON ###
+install:
+	pip install .
+
+install-dev:
+	pip install -e ".[dev]"
+
+test:
+	python -m pytest --junitxml=./reports/junit.xml -o junit_suite_name=$(PKGNAME) $(PKGNAME)
+
+test-cov:
+	python -m pytest --cov ./ --cov-report term-missing --cov-report xml:reports/coverage.xml --cov-report html:reports/coverage $(ALLNAMES)
+
+flake8: 
+	python -m pytest --flake8
+
+docstyle: 
+	python -m pytest --pydocstyle
 
+doc:
+	cd doc && make html
+	cd ..
 
+.PHONY: install install-dev doc clean test test-cov flake8 docstyle buildremote

README.md

-# KM3BUU
-
-The KM3BUU project is an integrated environment for the GiBUU studies within the KM3NeT experiment.
-
-## Installation
-The project is based on images using `singularity`, for which version 3 or higher (e.g. [v3.4](https://sylabs.io/guides/3.4/user-guide/)) is required. This is done due to the intention to provide a comparable installation on all systems and thus make the results 
-easily reproducible. The main project control is based on `make`.
-In order to apply installation commands presented within this section, clone this repository and change to the project directory:
-```
-git clone https://git.km3net.de/simulation/km3buu
-cd km3buu
-```
-
-
-### Local Machine
-By "Local Machine" a computer where are root (administrative) privileges are available is 
-meant. These root privileges are required to build the singularity image by yourself. In order to start the build, run the following `make` command:
-```
-make build
-```
-
-### Compute Cluster
-In order to make this project also usable in a non-root environment, the Image is also provided via the KM3NeT Docker-Server. Within KM3NeT computing infrastructure this is the case for the lyon compute cluster, thus this case is customised for this environment.
-
-In order to build the singularity image based on the remote image, run the following `make` command:
-```
-make buildremote
-```
-
-## Structure & Usage
-
-The used GiBUU jobcards are located in a sub-folder within the jobcards folder.
-Each sub-folder represents a set of jobcards, which can be processed by:
-
-```
-make run CARDSET=examples
-```
-
-This command runs all jobcards within the `jobcards/examples` folder and writes the output it to the folder `output`. The folder structure is applied from the `jobcards`folder.

README.rst

+KM3BUU
+======
+
+The KM3BUU project is an integrated environment for the GiBUU studies
+within the KM3NeT experiment.
+
+Installation
+------------
+
+The project is based on images using ``singularity``, for which version
+3 or higher (e.g. `v3.4 <https://sylabs.io/guides/3.4/user-guide/>`__)
+is required. This is done due to the intention to provide a comparable
+installation on all systems and thus make the results easily
+reproducible. The main project control is based on ``make``. In order to
+apply installation commands presented within this section, clone this
+repository and change to the project directory:
+
+::
+
+   git clone https://git.km3net.de/simulation/km3buu
+   cd km3buu
+
+Local Machine
+~~~~~~~~~~~~~
+
+By “Local Machine” a computer where are root (administrative) privileges
+are available is meant. These root privileges are required to build the
+singularity image by yourself. In order to start the build, run the
+following ``make`` command:
+
+::
+
+   make build
+
+Compute Cluster
+~~~~~~~~~~~~~~~
+
+In order to make this project also usable in a non-root environment, the
+Image is also provided via the KM3NeT Docker-Server. Within KM3NeT
+computing infrastructure this is the case for the lyon compute cluster,
+thus this case is customised for this environment.
+
+In order to build the singularity image based on the remote image, run
+the following ``make`` command:
+
+::
+
+   make buildremote
+
+Structure & Usage
+-----------------
+
+The used GiBUU jobcards are located in a sub-folder within the jobcards
+folder. Each sub-folder represents a set of jobcards, which can be
+processed by:
+
+::
+
+   make run CARDSET=examples
+
+This command runs all jobcards within the ``jobcards/examples`` folder
+and writes the output it to the folder ``output``. The folder structure
+is applied from the ``jobcards``\ folder.

doc/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER	      =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4	= -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS	= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS	= $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: default help clean html html-noplot dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+default: html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html	    to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json	    to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub	    to make an epub"
+	@echo "  latex	    to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text	    to make text files"
+	@echo "  man	    to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info	    to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml	    to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  view       to open HTML output in browser"
+
+doc-dependencies:
+	pip install -Ur ../requirements.txt
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf auto_examples/
+	rm -rf modules/generated/*
+	rm -rf api/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/KM3Pipe.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/KM3Pipe.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/KM3Pipe"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/KM3Pipe"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: view
+view:
+	$(BROWSER) $(BUILDDIR)/html/index.html

doc/changelog.rst

+Changelog
+=========
+
+.. include:: ../CHANGELOG.rst

doc/conf.py

+# -*- coding: utf-8 -*-
+#
+# KM3Pipe documentation build configuration file, created by
+# sphinx-quickstart on Sat Oct  4 19:16:43 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+from datetime import date
+import sphinx_rtd_theme
+from pkg_resources import get_distribution
+
+import km3buu
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.viewcode',
+    'autoapi.extension',
+    'numpydoc',
+    'sphinxcontrib.programoutput',
+]
+
+autosummary_generate = True
+
+# Document Python Code
+autoapi_type = 'python'
+autoapi_dirs = ['../km3buu']
+autoapi_options = [
+    'members', 'undoc-members'
+    # , 'private-members', 'special-members'
+]
+autoapi_ignore = ["*/tests/*", "*test_*.py", "*/doc/conf.py"]
+autoapi_include_summaries = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+# The full version, including alpha/beta/rc tags.
+release = get_distribution('km3buu').version
+# The short X.Y version.
+version = '.'.join(release.split('.')[:2])
+short_version = '.'.join(version.split('.')[:2])
+
+
+# General information about the project.
+project = "KM3BUU {}".format(short_version)
+
+copyright = u'{0}, Johannes Schumann'.format(date.today().year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', '_templates', '**.ipynb_checkpoints']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# html_theme_options = {}
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "KM3BUU {}".format(short_version)
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = 'Home'
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = "_static/foo_logo_small_white.png"
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# 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']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {
+    '**': ['globaltoc.html', 'searchbox.html'],
+}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'KM3BUUdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    ('index', 'KM3BUU.tex', u'KM3BUU Documentation', u'Johannes Schumann',
+     'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_domain_indices = True
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [('index', 'km3buu', u'KM3BUU Documentation',
+              [u'Johannes Schumann'], 1)]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = []
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+# texinfo_no_detailmenu = False
+
+# don't show the method summary twice
+numpydoc_show_class_members = False

doc/contribute.rst

+Contribute
+==========
+
+You want to hack new features into ``foo`` or are just here to fix a
+bug? Great!

doc/index.rst

+.. include:: ../README.rst
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    self
+
+.. toctree::
+    :maxdepth: 2
+
+    user_guide
+    contribute
+    changelog
+
+    Code Coverage <https://simulation.pages.km3net.de/km3buu/coverage>
+    Source (Git) <https://git.km3net.de/simulation/km3buu>
+
+* :ref:`genindex`

doc/user_guide.rst

+User GUide
+==========
+
+Install ``km3buu`` and have fun!

jobcards/examples/example.job

@@ -3,7 +3,7 @@
 	flavor_ID = 2 		! 1:electron, 2:muon, 3:tau
 	nuXsectionMode = 6 	! 6: dSigmaMC
 	includeDIS = .true. 	! enables DIS events
-	printAbsorptionXS = T
+	printAbsorptionXS = .true.
 /
 
 &target
@@ -44,7 +44,7 @@
 
 
 &neutrinoAnalysis
-	outputEvents = .true	! output list of events and
+	outputEvents = .true.	! output list of events and
 				! all outgoing particles in
 				! each event to the file 
 				! FinalEvents.dat

km3buu/__init__.py

+__author__ = "Johannes Schumann"
+__copyright__ = "Copyright 2020, Johannes Schumann and the KM3NeT collaboration."
+__credits__ = []
+__license__ = "MIT"
+__maintainer__ = "Johannes Schumann"
+__email__ = "jschumann@km3net.de"
+__status__ = "Development"
+
+IMAGE_NAME = "GiBUU.simg"
+DOCKER_URL = "docker://docker.km3net.de/simulation/km3buu:latest"

km3buu/__version__.py

+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Filename: __version__.py
+"""
+Pep 386 compliant version info.
+
+    (major, minor, micro, alpha/beta/rc/final, #)
+    (1, 1, 2, 'alpha', 0) => "1.1.2.dev"
+    (1, 2, 0, 'beta', 2) => "1.2b2"
+
+"""
+from os.path import dirname, realpath, join
+
+from setuptools_scm import get_version
+
+version = "unknown version"
+
+try:
+    version = get_version(root="..", relative_to=__file__)
+except LookupError:
+    with open(join(realpath(dirname(__file__)), "version.txt"), "r") as fobj:
+        version = fobj.read()

km3buu/config.py

+#!/usr/bin/env python
+# coding=utf-8
+# Filename: config.py
+# Author: Johannes Schumann <jschumann@km3net.de>
+"""
+
+
+"""
+import os
+import click
+from os.path import isfile, isdir, join, dirname, abspath
+from configparser import ConfigParser, Error, NoOptionError, NoSectionError
+from thepipe.logger import get_logger
+from . import IMAGE_NAME
+from .environment import build_image
+
+__author__ = "Johannes Schumann"
+__copyright__ = "Copyright 2020, Johannes Schumann and the KM3NeT collaboration."
+__credits__ = []
+__license__ = "MIT"
+__maintainer__ = "Johannes Schumann"
+__email__ = "jschumann@km3net.de"
+__status__ = "Development"
+
+CONFIG_PATH = os.path.expanduser("~/.km3buu/config")
+
+log = get_logger(__name__)
+
+
+class Config(object):
+    def __init__(self, config_path=CONFIG_PATH):
+        self.config = ConfigParser()
+        self._config_path = config_path
+        if isfile(self._config_path):
+            self.config.read(self._config_path)
+        else:
+            os.makedirs(dirname(CONFIG_PATH), exist_ok=True)
+
+    def set(self, section, key, value):
+        if section not in self.config.sections():
+            self.config.add_section(section)
+        self.config.set(section, key, value)
+        with open(self._config_path, "w") as f:
+            self.config.write(f)
+
+    def get(self, section, key, default=None):
+        try:
+            value = self.config.get(section, key)
+            try:
+                return float(value)
+            except ValueError:
+                return value
+        except (NoOptionError, NoSectionError):
+            return default
+
+    @property
+    def gibuu_image_path(self):
+        section = "GiBUU"
+        key = "image_path"
+        image_path = self.get(section, key)
+        if image_path is None or not isfile(image_path):
+            dev_path = abspath(join(dirname(__file__), os.pardir, IMAGE_NAME))
+            if isfile(dev_path):
+                image_path = dev_path
+            elif click.confirm("Is the GiBUU image already available?", default=False):
+                image_path = click.prompt(
+                    "GiBUU image path?", type=click.Path(exists=True, dir_okay=False)
+                )
+            elif click.confirm("Install image from remote?", default=True):
+                default_dir = join(os.environ["HOME"], ".km3buu")
+                image_dir = click.prompt(
+                    "GiBUU image path (default: ~/.km3buu) ?",
+                    type=click.Path(exists=True, file_okay=False),
+                    default=default_dir,
+                )
+                image_path = build_image(image_dir)
+            self.set(section, key, image_path)
+        return image_path
+
+    @gibuu_image_path.setter
+    def gibuu_image_path(self, value):
+        section = "GiBUU"
+        key = "image_path"
+        self.set(section, key, value)

km3buu/ctrl.py

+# Filename: ctrl.py
+"""
+Run and control tools for GiBUU
+
+"""
+
+__author__ = "Johannes Schumann"
+__copyright__ = "Copyright 2020, Johannes Schumann and the KM3NeT collaboration."
+__credits__ = []
+__license__ = "MIT"
+__maintainer__ = "Johannes Schumann"
+__email__ = "jschumann@km3net.de"
+__status__ = "Development"
+
+import os
+from spython.main import Client
+from os.path import join, abspath, basename, isdir, isfile
+from tempfile import NamedTemporaryFile, TemporaryDirectory
+from thepipe.logger import get_logger
+
+from . import IMAGE_NAME
+from .config import Config
+from .jobcard import Jobcard, read_jobcard
+from .environment import is_singularity_version_greater, MIN_SINGULARITY_VERSION
+
+log = get_logger(basename(__file__))
+
+if not is_singularity_version_greater(
+        MIN_SINGULARITY_VERSION):  # pragma: no cover
+    log.error("Singularity version lower than %s" % MIN_SINGULARITY_VERSION)
+    raise OSError("Singularity version below %s" % MIN_SINGULARITY_VERSION)
+
+GIBUU_SHELL = """
+#!/bin/bash
+
+export LD_LIBRARY_PATH=/usr/local/lib
+
+if [ -z "$CONTAINER_GIBUU_EXEC+x" ];
+then
+    echo "No GIBUU executable provided via CONTAINER_GIBUU_EXEC";
+    exit 1
+fi;
+
+cd {0};
+
+$CONTAINER_GIBUU_EXEC < {1};
+"""
+
+
+def run_jobcard(jobcard, outdir, fluxfile=None):
+    """
+    Method for run
+
+    Parameters
+    ----------
+    jobcard: str, km3buu.JobCard
+        The jobcard which should be run, which can be an instance
+        of a jobcard object or a path to a jobcard
+    outdir: str 
+        The path to the directory the output should be written to.
+    fluxfile: str
+        Filepath of the custom flux file if initNeutrino/nuExp = 99
+    """
+    input_dir = TemporaryDirectory()
+    outdir = abspath(outdir)
+    log.info("Create temporary file for jobcard")
+    jobcard_fpath = join(input_dir.name, "tmp.job")
+
+    if isinstance(jobcard, str) and isfile(jobcard):
+        jobcard = read_jobcard(jobcard)
+
+    if "neutrino_induced" in jobcard and "nuexp" in jobcard[
+            "neutrino_induced"] and jobcard["neutrino_induced"]["nuexp"] == 99:
+        if fluxfile is None or not isfile(fluxfile):
+            raise IOError("Fluxfile not found!")
+        tmp_fluxfile = join(input_dir.name, basename(fluxfile))
+        os.system("cp %s %s" % (fluxfile, tmp_fluxfile))
+        log.info("Set FileNameFlux to: %s" % tmp_fluxfile)
+        jobcard["neutrino_induced"]["FileNameflux"] = tmp_fluxfile
+    if isinstance(jobcard, Jobcard):
+        with open(jobcard_fpath, "w") as f:
+            f.write(str(jobcard))
+    else:
+        log.error("No valid jobcard reference given: %s" % jobcard)
+    log.info("Create temporary file for associated runscript")
+    script_fpath = join(input_dir.name, "run.sh")
+    with open(script_fpath, "w") as f:
+        ctnt = GIBUU_SHELL.format(outdir, jobcard_fpath)
+        f.write(ctnt)
+    output = Client.execute(
+        Config().gibuu_image_path,
+        ["/bin/sh", script_fpath],
+        bind=[outdir, input_dir.name],
+        return_result=True,
+    )
+    msg = output["message"]
+    if isinstance(msg, str):
+        log.info("GiBUU output:\n %s" % msg)
+    else:
+        log.info("GiBUU output:\n %s" % msg[0])
+        log.error("GiBUU stacktrace:\n%s" % msg[1])
+    return output["return_code"]

km3buu/environment.py

+# Filename: environment.py
+"""
+Core functions for the package environment
+
+"""
+
+__author__ = "Johannes Schumann"
+__copyright__ = "Copyright 2020, Johannes Schumann and the KM3NeT collaboration."
+__credits__ = []
+__license__ = "MIT"
+__maintainer__ = "Johannes Schumann"
+__email__ = "jschumann@km3net.de"
+__status__ = "Development"
+
+import os
+from spython.main import Client
+from spython.utils import get_singularity_version
+from os.path import join, isdir, basename
+from thepipe.logger import get_logger
+from distutils.version import LooseVersion
+
+from . import IMAGE_NAME, DOCKER_URL
+
+log = get_logger(basename(__file__))
+
+MIN_SINGULARITY_VERSION = "3.3"
+
+
+def is_singularity_version_greater(min_version):  # pragma: no cover
+    singularity_version = LooseVersion(get_singularity_version().split()[-1])
+    retval = singularity_version > LooseVersion(MIN_SINGULARITY_VERSION)
+    return retval
+
+
+def build_image(output_dir):
+    if not isdir(output_dir):
+        raise OSError("Directory not found!")
+    image_path = join(output_dir, IMAGE_NAME)
+    return Client.build(DOCKER_URL, image=image_path, sudo=False, ext="simg")