Initial commit

README.md

+# Python Project Cookiecutter Template
+
+This is a template to bootstrap a Python Project including the setup for
+the KM3NeT CI facilities.
+
+## Usage
+
+You need to install `cookiecutter` on your computer first:
+
+    pip install cookiecutter
+
+To bootstrap a Python project, run:
+
+    cookiecutter https://git.km3net.de/templates/python-project.git
+
+The default `LICENSE` is MIT, feel free to replace it with the one you like.
+
+
+## Additional Setup
+
+After filling in the required metadata, create a Git repository on
+https://git.km3net.de/projects/new and proceed with the repository
+initialisation:
+
+    cd project_dir
+    git init
+    git add .
+    git commit -m 'Initial commit'
+    git tag -a 'vX.Y.Z' -m 'Release X.Y.Z'
+    git remote add origin git@git.km3net.de:YOURUSERNMAE/PROJECT.git
+    git push -u origin master
+    git push --tags
+
+
+## Features
+
+- unit tests
+- automatic documentation generation
+- API documentation
+- continuous integration on the KM3NeT GitLab server
+- and more...

cookiecutter.json

+{
+    "author": "Leo Szilard",
+    "email": "{{cookiecutter.author.lower()[0] + cookiecutter.author.split()[1].lower()}}@km3net.de",
+    "project_name": "Awesome",
+    "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_') }}",
+    "version": "0.1.0",
+    "description": "The {{ cookiecutter.project_name }} project",
+    "gitlab_username": "{{cookiecutter.email.split('@')[0]}}",
+    "gitlab_repo_path": "https://git.km3net.de/{{ cookiecutter.gitlab_username + '/' + cookiecutter.project_slug }}.git",
+    "_extensions": ["jinja2_time.TimeExtension"],
+    "_test": "{% print('hello') %}"
+}

{{cookiecutter.project_slug}}/.coveragerc

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

{{cookiecutter.project_slug}}/.gitignore

+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.pyxbldc
+
+# Version info
+{{cookiecutter.project_slug}}/version.py
+
+# Build stuff
+build/
+develop-eggs/
+dist/
+eggs/
+sdist/
+*.egg-info/
+*.egg
+.eggs
+pip-wheel-metadata
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+.coverage.*
+junit*.xml
+reports
+
+# Sphinx documentation
+doc/_build/
+doc/auto_examples/
+doc/modules/
+doc/api
+
+# Virtual env
+venv

{{cookiecutter.project_slug}}/.gitlab-ci.yml

+image: docker.km3net.de/base/python:3
+
+# Change pip's cache directory to be inside the project directory since we can
+# only cache local items.
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip
+    - venv/
+  key: "$CI_COMMIT_REF_SLUG"
+
+stages:
+  - test
+  - coverage
+  - doc
+  - release
+
+.virtualenv_template: &virtualenv_definition |
+  python -V
+  pip install virtualenv
+  virtualenv venv
+  source venv/bin/activate
+  pip install -r requirements-dev.txt
+  make install
+
+.junit_template: &junit_definition
+    artifacts:
+      reports:
+        junit: "reports/junit*.xml"
+
+test-py3.5:
+    image: docker.km3net.de/base/python:3.5
+    stage: test
+    script:
+        - *virtualenv_definition
+        - make test
+    <<: *junit_definition
+    allow_failure: true
+
+test-py3.6:
+    image: docker.km3net.de/base/python:3.6
+    stage: test
+    script:
+        - *virtualenv_definition
+        - make test
+    <<: *junit_definition
+
+test-py3.7:
+    image: docker.km3net.de/base/python:3.7
+    stage: test
+    script:
+        - *virtualenv_definition
+        - make test
+    <<: *junit_definition
+
+test-py3.8:
+    image: docker.km3net.de/base/python:3.8
+    stage: test
+    script:
+        - *virtualenv_definition
+        - make test
+    <<: *junit_definition
+
+code-style:
+    image: docker.km3net.de/base/python:3.7
+    stage: test
+    script:
+        - *virtualenv_definition
+        - yapf -r -d -e "venv" .
+    allow_failure: true
+
+coverage:
+    image: docker.km3net.de/base/python:3.6
+    stage: coverage
+    script:
+        - *virtualenv_definition
+        - make install-dev
+        - "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
+
+
+build-docs:
+    image: docker.km3net.de/base/python:3.6
+    stage: doc
+    script:
+        - *virtualenv_definition
+        - cd doc && make clean && make html
+    cache: {}
+
+pages:
+    image: docker.km3net.de/base/python:3.6
+    stage: doc
+    script:
+        - *virtualenv_definition
+        - cd doc && make clean && make html
+        - mv _build/html ../public/
+        - cd .. && mv reports/coverage public/coverage
+    artifacts:
+        paths:
+            - public
+    cache: {}
+    only:
+        - tags
+        - master
+
+
+pypi:
+    image: docker.km3net.de/base/python:3
+    stage: release
+    cache: {}
+    script:
+        - pip install -U twine wheel
+        - python setup.py sdist
+        - python setup.py bdist_wheel
+        - twine upload dist/*
+    only:
+        - tags

{{cookiecutter.project_slug}}/CHANGELOG.rst

+Unreleased changes
+------------------
+
+* Remove template artifacts
+
+{% set major_version = cookiecutter.version.split('.')[0] %}
+Version {{major_version}}
+--------{% for i in range(major_version|length) %}-{% endfor %}
+
+{{cookiecutter.version}} / {% now 'local' %}
+{% for i in range((cookiecutter.version|length) + 13) %}~{% endfor %}
+* Project generated using the cookiecutter template from
+  https://git.km3net.de/templates/python-project

{{cookiecutter.project_slug}}/LICENSE

+The MIT License (MIT)
+
+Copyright (c) 2014 Tamas Gal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

{{cookiecutter.project_slug}}/MANIFEST.in

+include README.rst
+include LICENSE
+include requirements.txt

{{cookiecutter.project_slug}}/Makefile

+PKGNAME={{cookiecutter.project_slug}}
+
+default: build
+
+all: install
+
+install: 
+	pip install .
+
+install-dev: dependencies-dev
+	pip install -e .
+
+venv:
+	python3 -m venv venv
+
+clean:
+	python3 setup.py clean --all
+	rm -rf venv
+
+test: 
+	py.test --junitxml=./reports/junit.xml -o junit_suite_name=$(PKGNAME) tests
+
+test-cov:
+	py.test --cov ./$(PKGNAME) --cov-report term-missing --cov-report xml:reports/coverage.xml --cov-report html:reports/coverage tests
+
+test-loop: 
+	py.test tests
+	ptw --ext=.py,.pyx --ignore=doc tests
+
+dependencies:
+	pip install -Ur requirements.txt
+
+dependencies-dev:
+	pip install -Ur requirements-dev.txt
+
+yapf:
+	yapf -i -r $(PKGNAME)
+	yapf -i -r tests
+	yapf -i setup.py
+
+.PHONY: all clean install install-dev venv test test-cov test-loop dependencies dependencies-dev yapf

{{cookiecutter.project_slug}}/README.rst

+{{cookiecutter.description}}
+{% for i in range(cookiecutter.description|length) %}={% endfor %}
+
+.. image:: {{cookiecutter.gitlab_repo_path}}/badges/master/pipeline.svg
+    :target: {{cookiecutter.gitlab_repo_path}}/pipelines
+
+.. image:: {{cookiecutter.gitlab_repo_path}}/badges/master/coverage.svg
+    :target: https://{{cookiecutter.gitlab_username}}.pages.km3net.de/{{cookiecutter.project_slug}}/coverage
+
+.. image:: https://examples.pages.km3net.de/km3badges/docs-latest-brightgreen.svg
+    :target: https://{{cookiecutter.gitlab_username}}.pages.km3net.de/{{cookiecutter.project_slug}}
+

{{cookiecutter.project_slug}}/doc/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

{{cookiecutter.project_slug}}/doc/_static/default.css

+.rst-content .highlight>pre {
+    line-height: 18px;
+}

{{cookiecutter.project_slug}}/doc/changelog.rst

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

{{cookiecutter.project_slug}}/doc/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import sys
+import os
+from datetime import date
+import sphinx_rtd_theme
+from pkg_resources import get_distribution
+
+# -- Project information -----------------------------------------------------
+
+version = get_distribution('{{cookiecutter.project_slug}}').version
+short_version = '.'.join(version.split('.')[:2])
+project = '{{cookiecutter.project_slug}} {}'.format(short_version)
+copyright = '{0}, {{cookiecutter.author}}'.format(date.today().year)
+author = '{{cookiecutter.author}}'
+
+# -- General configuration ---------------------------------------------------
+
+# 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.viewcode',
+    'autoapi.extension', 'numpydoc',
+    'sphinx_gallery.gen_gallery'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'version.py']
+
+# AutoAPI
+autoapi_type = 'python'
+autoapi_dirs = ['../{{cookiecutter.project_slug}}']
+autoapi_ignore = ['*version.py*']
+autoapi_add_toctree_entry = True
+
+# Gallery
+sphinx_gallery_conf = {
+    'backreferences_dir': 'modules/generated',
+    'default_thumb_file': '_static/default_gallery_thumbnail.png',
+    'examples_dirs': '../examples',  # path to your example scripts
+    'gallery_dirs':
+    'auto_examples',  # path to where to save gallery generated output
+    'show_memory': True,
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# 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_title = "{{cookiecutter.project_slug}} {}".format(version)

{{cookiecutter.project_slug}}/doc/examples.rst

+========
+Examples
+========
+
+.. include:: auto_examples/index.rst

{{cookiecutter.project_slug}}/doc/index.rst

+.. include:: ../README.rst
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   examples
+   changelog
+
+   autoapi/index
+
+   Code Coverage <http://{{cookiecutter.gitlab_username}}.pages.km3net.de/{{cookiecutter.project_slug}}/coverage>
+   Source (Git) <{{cookiecutter.gitlab_repo_path}}>
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

{{cookiecutter.project_slug}}/doc/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

{{cookiecutter.project_slug}}/examples/README.rst

+Collection of Examples
+======================
+
+All of these examples are auto-generated each time the documentation is built.

{{cookiecutter.project_slug}}/examples/plot_calculator.py

+"""
+How to use the Calculator
+=========================
+
+The following example shows how to use the `Calculator` class.
+"""
+from {{cookiecutter.project_slug}} import Calculator
+
+#####################################################
+# Initialising a Calculator
+# -------------------------
+# Initialising is a simple as this:
+
+calc = Calculator()
+
+#####################################################
+# Adding numbers
+# ~~~~~~~~~~~~~~
+#
+# You can add two numbers by calling the `.add(a, b)` method:
+
+print(calc.add(5, 23))