Skip to content
Snippets Groups Projects
Commit c4183086 authored by Benjamin Trocme's avatar Benjamin Trocme
Browse files

Initial commit

parents
No related branches found
Tags v0.1.0
No related merge requests found
Pipeline #50251 passed with warnings with stages
in 4 minutes and 11 seconds
[run]
source = km3dq_common
[report]
omit =
src/km3dq_common/version.py
exclude_lines =
pragma: no cover
raise AssertionError
raise NotImplementedError
if 0:
if __name__ == .__main__.:
if self.debug:
if settings.DEBUG
def __repr__
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*.pyxbldc
# Version info
src/km3dq_common/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/gen_modules/*.examples
doc/api
# Virtual env
venv
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
stages:
- test
- coverage
- doc
- release
.virtualenv_template: &virtualenv_definition |
python -V
python3 -m venv venv
source venv/bin/activate
pip install -U pip setuptools wheel setuptools_scm
hash -r
pip freeze
make install-dev
pip freeze
.junit_template: &junit_definition
artifacts:
reports:
junit: "reports/junit*.xml"
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
test-py3.9:
image: docker.km3net.de/base/python:3.9
stage: test
script:
- *virtualenv_definition
- make test
<<: *junit_definition
test-py3.10:
image: docker.km3net.de/base/python:3.10
stage: test
script:
- *virtualenv_definition
- make test
<<: *junit_definition
code-style:
image: docker.km3net.de/base/python:3.9
stage: test
script:
- *virtualenv_definition
- make black-check
allow_failure: true
coverage:
image: docker.km3net.de/base/python:3.9
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]*%)/'
artifacts:
paths:
- reports/coverage
build-docs:
image: docker.km3net.de/base/python:3.9
stage: doc
script:
- *virtualenv_definition
- cd doc && make clean && make html
cache: {}
pages:
image: docker.km3net.de/base/python:3.9
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.9
stage: release
cache: {}
script:
- pip install -U twine wheel setuptools_scm
- python setup.py sdist
- python setup.py bdist_wheel
- twine upload dist/*
only:
- tags
allow_failure: true
Unreleased changes
------------------
* Remove template artifacts
Version 0
---------
0.1.0 / 2024-04-16
~~~~~~~~~~~~~~~~~~
* Project generated using the cookiecutter template from
https://git.km3net.de/templates/python-project
Filing Bugs or Feature Requests
-------------------------------
Please **always** create an issue when you encounter any bugs, problems or
need a new feature. Emails and private messages are not meant to communicate
such things!
Use the appropriate template and file a new issue here:
https://git.km3net.de/btrocme/km3dq_common/issues
You can browse all the issues here: https://git.km3net.de/btrocme/km3dq_common/issues
Please follow the instructions in the templates to provide all the
necessary information which will help other people to understand the
situation.
Improve
-------
Check out our KanBan board https://git.km3net.de/btrocme/km3dq_common/boards,
which shows all the open issues in three columns:
- *discussion*: The issues which are yet to be discussed (e.g. not clear how to proceed)
- *todo*: Issues tagged with this label are ready to be tackled
- *doing*: These issues are currently "work in progress". They can however be
put tossed back to *todo* column at any time if the development is suspended.
Here is the recommended workflow if you want to improve this project. This is a
standard procedure for collaborative software development, nothing exotic!
Feel free to contribute ;)
Make a Fork
~~~~~~~~~~~
You create a fork (your full own copy of the
repository), change the code and when you are happy with the changes, you create
a merge request, so we can review, discuss and add your contribution.
Merge requests are automatically tested on our GitLab CI server and you
don't have to do anything special.
Go to https://git.km3net.de/btrocme/km3dq_common and click on "Fork".
After that, you will have a full copy of the code with write access under an URL
like this: ``https://git.km3net.de/YOUR_USERNAME/km3dq_common``
Clone your Fork to your PC
~~~~~~~~~~~~~~~~~~~~~~~~~~
Get a local copy to work on (use the SSH address `git@git...`, not the HTTP one)::
git clone git@git.km3net.de:YOUR_USERNAME/km3dq_common
Now you need to add a reference to the original repository, so you can sync your
own fork with the original repository::
cd km3dq_common
git remote add upstream https://git.km3net.de/btrocme/km3dq_common
Keep your Fork Up to Date
~~~~~~~~~~~~~~~~~~~~~~~~~
To get the most recent commits (including all branches), run::
git fetch upstream
This will download all the missing commits and branches which are now accessible
using the ``upstream/...`` prefix::
$ git fetch upstream
From km3dq_common
* [new branch] gitlab_jenkins_ci_test -> upstream/gitlab_jenkins_ci_test
* [new branch] legacy -> upstream/legacy
* [new branch] master -> upstream/master
If you want to update for example your **own** ``master`` branch
to contain all the changes on the official ``master`` branch of the original repository,
switch to it first with::
git checkout master
and then merge the ``upstream/master`` into it::
git merge upstream/master
Make sure to regularly ``git fetch upstream`` and merge changes to your own branches.
Push your changes to Gitlab regularly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure to keep your fork up to date on the GitLab server by pushing
all your commits regularly using::
git push
Install in Developer Mode
~~~~~~~~~~~~~~~~~~~~~~~~~
This project can be installed in ``dev-mode``, which means, it links itself to
your site-packages and you can edit the sources and test them without the need
to reinstall it all the time. Although you will need to restart any
``python``, ``ipython`` or ``jupyter``-notebook (only the kernel!) if you
imported this python package before you made the changes.
Go to your own fork folder (as described above) and check out the branch you
want to work on::
git checkout master # the main development branch (should always be stable)
make install-dev
Running the Test Suite
~~~~~~~~~~~~~~~~~~~~~~
Make sure to run the test suite first to see if everything is working
correctly::
$ make test
This should give you a green bar!
Run the tests every time you make changes to see if you broke anything! It usually
takes just a few seconds and ensures that you don't break existing code. It's
also an easy way to spot syntax errors ;)
You can also start a script which will watch for file changes and retrigger
a test suite run every time for you. It's a nice practice to have a terminal
open running this script to check your test results continuously::
make test-loop
Time to Code
~~~~~~~~~~~~
We develop new features and fix bugs on separate branches and merge them
back to ``master`` when they are stable. Merge requests (see below) are also
pointing towards this branch.
If you are working on your own fork, you can stay on your own ``master`` branch
and create merge requests from that.
Code Style
~~~~~~~~~~
Make sure to run ``black`` over the code, which ensures that the code style
matches the one we love and respect. We have a tool which makes it easy::
make black
Create a Merge Request (aka Pull Request)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Go to https://git.km3net.de/btrocme/km3dq_common/merge_requests/new and select your
source branch, which contains the changes you want to be added to this project
and select the ``master`` branch as target branch.
That's it, the merge will be accepted if everything is OK ;)
If you want to join the dev-team, let us know! Once you are a member of the
project, you can work on branches in this repository, without the need to
use your own fork :)
LICENSE 0 → 100644
BSD 3-Clause License
Copyright (c) YEAR, The KM3NeT collaboration
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
include README.rst
include LICENSE
include requirements/*.txt
Makefile 0 → 100644
install:
pip install .
install-dev:
pip install -e ".[dev]"
python -m ipykernel install --user --name=km3dq_common
clean:
python setup.py clean --all
test:
py.test --junitxml=./reports/junit.xml -o junit_suite_name=km3dq_common tests
test-cov:
py.test --cov src/km3dq_common --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
flake8:
py.test --flake8
pep8: flake8
docstyle:
py.test --docstyle
lint:
py.test --pylint
.PHONY: black
black:
black --exclude 'version.py' src/km3dq_common
black examples
black tests
black doc/conf.py
black setup.py
.PHONY: black-check
black-check:
black --check --exclude 'version.py' src/km3dq_common
black --check examples
black --check tests
black --check doc/conf.py
black --check setup.py
.PHONY: all clean install install-dev test test-nocov flake8 pep8 docstyle black black-check
Common library for km3dq packages
=================================
.. image:: https://git.km3net.de/btrocme/km3dq_common/badges/master/pipeline.svg
:target: https://git.km3net.de/btrocme/km3dq_common/pipelines
.. image:: https://git.km3net.de/btrocme/km3dq_common/badges/master/coverage.svg
:target: https://btrocme.pages.km3net.de/km3dq_common/coverage
.. image:: https://git.km3net.de/examples/km3badges/-/raw/master/docs-latest-brightgreen.svg
:target: https://btrocme.pages.km3net.de/km3dq_common
Installation
~~~~~~~~~~~~
It is recommended to first create an isolated virtualenvironment to not interfere
with other Python projects::
git clone https://git.km3net.de/btrocme/km3dq_common
cd km3dq_common
python3 -m venv venv
. venv/bin/activate
Install directly from the Git server via ``pip`` (no cloneing needed)::
pip install git+https://git.km3net.de/btrocme/km3dq_common
Or clone the repository and run::
make install
To install all the development dependencies, in case you want to contribute or
run the test suite::
make install-dev
make test
---
*Created with ``cookiecutter https://git.km3net.de/templates/python-project``*
# 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)
.rst-content .highlight>pre {
line-height: 18px;
}
doc/_static/default_gallery_thumbnail.png

23.7 KiB

Changelog
=========
.. include:: ../CHANGELOG.rst
# 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
try:
from importlib.metadata import version as get_version
version = get_version('km3dq_common')
except ImportError:
from pkg_resources import get_distribution
version = get_distribution('km3dq_common').version
# -- Project information -----------------------------------------------------
short_version = '.'.join(version.split('.')[:2])
project = 'km3dq_common {}'.format(short_version)
copyright = '{0}, Benjamin Trocme'.format(date.today().year)
author = 'Benjamin Trocme'
# -- 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 = ['../src/km3dq_common']
autoapi_options = ["members", "undoc-members", "show-module-summary"]
autoapi_include_summaries = True
# Gallery
sphinx_gallery_conf = {
'backreferences_dir': 'gen_modules',
'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
}
# -- 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 = "km3dq_common {}".format(version)
.. include:: ../CONTRIBUTING.rst
========
Examples
========
.. include:: auto_examples/index.rst
.. include:: ../README.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
examples
contribute
changelog
autoapi/index
Code Coverage <http://btrocme.pages.km3net.de/km3dq_common/coverage>
Source (Git) <https://git.km3net.de/btrocme/km3dq_common>
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
@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
Collection of Examples
======================
All of these examples are auto-generated each time the documentation is built.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment