Commit 18d23ea9 authored by Matt Clarkson's avatar Matt Clarkson
Browse files

Initial commit

Pipeline #3712 passed with stages
in 6 minutes and 56 seconds
omit =
labelboxutils/ export-subst
# Pycharm
# Generated files
# PyInstaller
# Jupyter output
#Tell Gitlab to load these environental vars from the variables list
- build
- installer
- test
- deploy
# Define a template stage with common settings
# that can be extended by specific stages.
# The except block will skip this stage if the commit
# message contains [skip build]
.build-skip-template: &build-skip-template
stage: build
- $CI_COMMIT_MESSAGE =~ /\[skip[ _-]build?\]/i
.build-install-template: &build-install-template
- tox -e installer
- dist/
expire_in: 1 week
# The win/mac/linux build stages inherit settings
# from build-install-template
build linux installer:
<<: *build-skip-template
<<: *build-install-template
- shared-linux
build mac installer:
<<: *build-skip-template
<<: *build-install-template
- shared-mac
build windows installer:
<<: *build-skip-template
<<: *build-install-template
- shared-win
build docs:
<<: *build-skip-template
- tox -e docs
- shared-linux
- doc/
expire_in: 1 week
test Linux:
stage: test
- tox
- shared-linux
coverage: '/^TOTAL.*\s+(\d+\%)$/'
test macOS:
stage: test
- tox
- shared-mac
test Windows:
stage: test
- tox
- shared-win
# Template for deploy stages that depend on 'build docs'
# if the build stage is skipped, skip these also
.deploy-docs-skip-template: &deploy-docs-skip-template
stage: deploy
when: manual
- $CI_COMMIT_MESSAGE =~ /\[skip[ _-]build?\]/i
- build docs
deploy docs to staging:
<<: *deploy-docs-skip-template
# Note: the group/username directory must already exist on the server before calling this command
- rsync -avz -e'ssh -v' --numeric-ids --delete doc/build/html/* staging_docs_rsync:WEISS/SoftwareRepositories/LabelboxUtils 2>&1
- docs-staging
name: staging
- master
deploy docs to production:
<<: *deploy-docs-skip-template
# Note: the group/username directory must already exist on the server before calling this command
- rsync -avz -e'ssh -v' --numeric-ids --delete doc/build/html/* production_docs_rsync:WEISS/SoftwareRepositories/LabelboxUtils 2>&1
- docs-production
name: production
- public
deploy pip to PyPI:
stage: deploy
when: manual
- tags
name: PyPI
- pip-production
- dist/
# Install packages required to build/publish
# remove any previous distribution files
- pip install wheel twine setuptools
- rm -rf dist
# bundle installer
- python bdist_wheel
# Upload to pypi
- twine upload --repository pypi dist/* --username $PYPI_USER --password $PYPI_PASS
.. highlight:: shell
Contributing to Labelbox Utils
We welcome contributions to Labelbox Utils.
Reporting bugs and feature requests
Please create a new issue on
When reporting a bug, please include:
* The version of Labelbox Utils you are using
* Your OS version (for example Windows 10 64-bit, macOS High Sierra, Ubuntu 16.04)
* Detailed steps to reproduce the bug.
Fixing bugs or implement features
The easiest way to contribute is to follow these guidelines:
1. Look through the issues on and assign the relevant issue to yourself. If there is not an existing issue that covers your work, please create one:
2. Read the design considerations below.
3. Fork the repository:
4. Create a branch for your changes. The branch name should start with the issue number, followed by hyphen separated words describing the issue. For example: 1-update-contribution-guidelines
5. Make your changes following the coding guidelines below.
6. Commit and push your changes to your fork. The commit message should start with `Issue #<issue number>`, for example: "Issue #1: Fixed typo". Commit in small, related chunks. Review each commit and explain its purpose in the commit message.
7. Submit a merge request:
Design Considerations
1. As few dependencies as possible. Try to stick to standard scipy packages like numpy and pandas.
2. Discuss extra dependencies with the team and maybe the outcome will be to create a new separate package, where you can be more specific and more modular.
3. Unit test well, using pytest, with good coverage.
4. All errors as exceptions rather than return codes.
Coding guidelines
1. Please follow PEP8 guidelines
2. Create a python virtual environment (virtualenv) for development
3. Make sure that pylint passes. You may disable specific warnings within the code where it is reasonable to do so
4. Add unit tests for new and modified code
5. Make sure all existing and new tests pass
6. Make sure all docstrings have been added
7. Make sure all dependencies have been added to requirements
8. Make sure your code works for all required versions of Python
9. Make sure your code works for all required operating systems
Apache Software License 2.0
Copyright (c) 2019, University College London
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
include labelboxutils/
Labelbox Utils
.. image::
:height: 128px
:width: 128px
:alt: Logo
.. image::
:alt: GitLab-CI test status
.. image::
:alt: Test coverage
.. image::
:alt: Documentation Status
Author: Matt Clarkson
Labelbox Utils is part of the `SNAPPY`_ software project, developed at the `Wellcome EPSRC Centre for Interventional and Surgical Sciences`_, part of `University College London (UCL)`_.
Labelbox Utils supports Python 2.7 and Python 3.6.
Labelbox Utils is currently a demo project, which will add/multiply two numbers. Example usage:
python 5 8
python 3 6 --multiply
Please explore the project structure, and implement your own functionality.
You can clone the repository using the following command:
git clone
Running tests
Pytest is used for running unit tests:
pip install pytest
python -m pytest
This code conforms to the PEP8 standard. Pylint can be used to analyse the code:
pip install pylint
pylint --rcfile=tests/pylintrc labelboxutils
You can pip install directly from the repository as follows:
pip install git+
Please see the `contributing guidelines`_.
Useful links
* `Source code repository`_
* `Documentation`_
Licensing and copyright
Copyright 2019 University College London.
Labelbox Utils is released under the Apache Software License 2.0. Please see the `license file`_ for details.
Supported by `Wellcome`_ and `EPSRC`_.
.. _`Wellcome EPSRC Centre for Interventional and Surgical Sciences`:
.. _`source code repository`:
.. _`Documentation`:
.. _`SNAPPY`:
.. _`University College London (UCL)`:
.. _`Wellcome`:
.. _`EPSRC`:
.. _`contributing guidelines`:
.. _`license file`:
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# LabelboxUtils documentation build configuration file, created by
# sphinx-quickstart on Tue Dec 19 17:02:44 2017.
# 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 subprocess
import os
import sys
# 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('.'))
working_dir = os.path.abspath(os.path.dirname(__file__))
root_dir_rel = os.path.join('..')
root_dir_abs = os.path.abspath(root_dir_rel)
module_path = root_dir_abs
sys.path.insert(0, module_path)
logo_file = 'project-icon.png'
logo_path = os.path.join('..', logo_file)
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = [
# 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".
static_folder = 'static'
html_static_path = [static_folder]
def generate_apidocs(*args):
"""Generate API docs automatically by trawling the available modules"""
global working_dir, module_path
output_path = working_dir
apidoc_command_path = 'sphinx-apidoc'
if hasattr(sys, 'real_prefix'): # called from a virtualenv
apidoc_command_path = os.path.join(sys.prefix, 'bin', 'sphinx-apidoc')
apidoc_command_path = os.path.abspath(apidoc_command_path)
[apidoc_command_path, '--force', '--separate'] +
['-o', output_path, module_path] +
[os.path.join(root_dir_abs, pattern) for pattern in exclude_patterns])
def setup(app):
# Hook to allow for automatic generation of API docs
# before doc deployment begins.
app.connect('builder-inited', generate_apidocs)
# -- 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.viewcode', 'sphinx.ext.imgmath', 'nbsphinx']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# This allows modules to be indexed under the submodule name rather than all appearing under labelboxutils
modindex_common_prefix = [
# General information about the project.
project = u'Labelbox Utils'
copyright = u"2019, University College London"
author = u'Matt Clarkson'
# 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 short X.Y version.
version = u''
# The full version, including alpha/beta/rc tags.
release = u''
# The short X.Y version.
# version = labelboxutils.__version__
# The full version, including alpha/beta/rc tags.
# release = labelboxutils.__version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- 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 = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
doc_black = '#0A0A0A'
doc_red = '#E03C31'
doc_gray = '#979999'
doc_blue = '#00627D'
doc_dark_red = '#C53B2C'
doc_white = '#FEFEFE'
html_theme_options = {
'footerbgcolor': doc_gray,
'footertextcolor': doc_black,
'sidebarbgcolor': doc_white,
'sidebartextcolor': doc_black,
'sidebarlinkcolor': doc_red,
'relbarbgcolor': doc_white,
'relbartextcolor': doc_black,
'relbarlinkcolor': doc_red,
'bgcolor': doc_white,
'textcolor': doc_black,
'linkcolor': doc_red,
'visitedlinkcolor': doc_dark_red,
'headbgcolor': doc_white,
'headtextcolor': doc_black,
'headlinkcolor': doc_red,
'codebgcolor': doc_blue,
'codetextcolor': doc_black,
'stickysidebar': 'true',
html_logo = logo_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']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
# This is required for the alabaster theme
# refs:
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'LabelboxUtilsdoc'
# -- 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': '',
# Latex figure (float) alignment
# 'figure_align': 'htbp',
# 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', 'LabelboxUtils.tex',
u'Labelbox Utils Documentation',
u'Matt Clarkson', 'manual'),
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'LabelboxUtils',
u'Labelbox Utils Documentation',
[u'Matt Clarkson'], 1)
# -- 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 = [
('index', 'LabelboxUtils',
u'Labelbox Utils Documentation',
u'Matt Clarkson',
'One line description of project.',
.. include:: ../README.rst