Commit 58389f5b authored by Matt Clarkson's avatar Matt Clarkson

Initial commit

parents
Pipeline #3171 passed with stages
in 30 minutes and 11 seconds
[run]
omit =
./yfmil3id2019/_version.py
./yfmil3id2019/__init__.py
./yfmil3id2019/__main__.py
./yfmil3id2019/ui/yfmil3id2019_command_line.py
yfmil3id2019/_version.py export-subst
# Pycharm
/.idea
# Generated files
.tox
.coverage
*.pyc
.pytest_cache/
# PyInstaller
build/
dist/
#Tell Gitlab to load these environental vars from the variables list
variables:
PYPI_USER: SECURE
PYPI_PASS: SECURE
stages:
- 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
except:
variables:
- $CI_COMMIT_MESSAGE =~ /\[skip[ _-]build?\]/i
.build-install-template: &build-install-template
script:
- tox -e installer
artifacts:
paths:
- 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
tags:
- shared-linux
build mac installer:
<<: *build-skip-template
<<: *build-install-template
tags:
- shared-mac
build windows installer:
<<: *build-skip-template
<<: *build-install-template
tags:
- shared-win
build docs:
<<: *build-skip-template
script:
- tox -e docs
tags:
- shared-linux
artifacts:
paths:
- doc/
expire_in: 1 week
test Linux:
stage: test
script:
- tox
tags:
- shared-linux
coverage: '/^TOTAL.*\s+(\d+\%)$/'
test macOS:
stage: test
script:
- tox
tags:
- shared-mac
test Windows:
stage: test
script:
- tox
tags:
- 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
except:
variables:
- $CI_COMMIT_MESSAGE =~ /\[skip[ _-]build?\]/i
dependencies:
- build docs
deploy docs to staging:
<<: *deploy-docs-skip-template
script:
# 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/SNAPPY/yunguanfu-mil3id2019 2>&1
tags:
- docs-staging
environment:
name: staging
url: http://weisslab-lin.cs.ucl.ac.uk/staging/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019
only:
- master
deploy docs to production:
<<: *deploy-docs-skip-template
script:
# 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/SNAPPY/yunguanfu-mil3id2019 2>&1
tags:
- docs-production
environment:
name: production
only:
- public
deploy pip to PyPI:
stage: deploy
when: manual
only:
- tags
environment:
name: PyPI
url: https://pypi.python.org/pypi/yunguanfu-mil3id2019
tags:
- pip-production
artifacts:
paths:
- dist/
script:
# Install packages required to build/publish
# remove any previous distribution files
- pip install wheel twine setuptools
- rm -rf dist
# bundle installer
- python setup.py bdist_wheel
# Upload to pypi
- twine upload --repository pypi dist/* --username $PYPI_USER --password $PYPI_PASS
.. highlight:: shell
===============================================
Contributing to yunguanfu-mil3id2019
===============================================
We welcome contributions to yunguanfu-mil3id2019.
Reporting bugs and feature requests
-----------------------------------
Please create a new issue on https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/issues/new
When reporting a bug, please include:
* The version of yunguanfu-mil3id2019 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 https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/issues and assign the relevant issue to yourself. If there is not an existing issue that covers your work, please create one: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/issues/new
2. Read the design considerations below.
3. Fork the repository: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/forks/new
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: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/merge_requests/new
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 https://www.python.org/dev/peps/pep-0008/
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
BSD License
Copyright (c) 2019, University College London
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 versioneer.py
include yfmil3id2019/_version.py
yunguanfu-mil3id2019
===============================
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/raw/master/project-icon.png
:height: 128px
:width: 128px
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019
:alt: Logo
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/badges/master/build.svg
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/pipelines
:alt: GitLab-CI test status
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/badges/master/coverage.svg
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/commits/master
:alt: Test coverage
.. image:: https://readthedocs.org/projects/yunguanfu-mil3id2019/badge/?version=latest
:target: http://yunguanfu-mil3id2019.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
Author: Yunguan Fu
yunguanfu-mil3id2019 is part of the `SNAPPY`_ software project, developed at the `Wellcome EPSRC Centre for Interventional and Surgical Sciences`_, part of `University College London (UCL)`_.
yunguanfu-mil3id2019 supports Python 2.7 and Python 3.6.
yunguanfu-mil3id2019 is currently a demo project, which will add/multiply two numbers. Example usage:
::
python yfmil3id2019.py 5 8
python yfmil3id2019.py 3 6 --multiply
Please explore the project structure, and implement your own functionality.
Developing
----------
Cloning
^^^^^^^
You can clone the repository using the following command:
::
git clone https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019
Running tests
^^^^^^^^^^^^^
Pytest is used for running unit tests:
::
pip install pytest
python -m pytest
Linting
^^^^^^^
This code conforms to the PEP8 standard. Pylint can be used to analyse the code:
::
pip install pylint
pylint --rcfile=tests/pylintrc yfmil3id2019
Installing
----------
You can pip install directly from the repository as follows:
::
pip install git+https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019
Contributing
^^^^^^^^^^^^
Please see the `contributing guidelines`_.
Useful links
^^^^^^^^^^^^
* `Source code repository`_
* `Documentation`_
Licensing and copyright
-----------------------
Copyright 2019 University College London.
yunguanfu-mil3id2019 is released under the BSD-3 license. Please see the `license file`_ for details.
Acknowledgements
----------------
Supported by `Wellcome`_ and `EPSRC`_.
.. _`Wellcome EPSRC Centre for Interventional and Surgical Sciences`: http://www.ucl.ac.uk/weiss
.. _`source code repository`: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019
.. _`Documentation`: https://yunguanfu-mil3id2019.readthedocs.io
.. _`SNAPPY`: https://weisslab.cs.ucl.ac.uk/WEISS/PlatformManagement/SNAPPY/wikis/home
.. _`University College London (UCL)`: http://www.ucl.ac.uk/
.. _`Wellcome`: https://wellcome.ac.uk/
.. _`EPSRC`: https://www.epsrc.ac.uk/
.. _`contributing guidelines`: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/blob/master/CONTRIBUTING.rst
.. _`license file`: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/SNAPPY/yunguanfu-mil3id2019/blob/master/LICENSE
/yfmil3id2019.rst
/yfmil3id2019.*.rst
/modules.rst
/versioneer.rst
/build
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# yunguanfu-mil3id2019 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 = [
'tests',
'run_*',
'setup.py',
'_build',
'Thumbs.db',
'.DS_Store',
'_verion.py',
'versioneer.py'
]
# 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)
subprocess.check_call(
[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']
# 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 yfmil3id2019
modindex_common_prefix = [
'yfmil3id2019.'
]
# General information about the project.
project = u'yunguanfu-mil3id2019'
copyright = u"2019, University College London"
author = u'Yunguan Fu'
# 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 = yfmil3id2019.__version__
# The full version, including alpha/beta/rc tags.
# release = yfmil3id2019.__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: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'yunguanfu-mil3id2019doc'
# -- 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', 'yunguanfu-mil3id2019.tex',
u'yunguanfu-mil3id2019 Documentation',
u'Yunguan Fu', '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', 'yunguanfu-mil3id2019',
u'yunguanfu-mil3id2019 Documentation',
[u'Yunguan Fu'], 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', 'yunguanfu-mil3id2019',
u'yunguanfu-mil3id2019 Documentation',
u'Yunguan Fu',
'yunguanfu-mil3id2019',
'One line description of project.',
'Miscellaneous'),
]
.. include:: ../README.rst
Contents
~~~~~~~~
.. toctree::
:maxdepth: 1
requirements
Module Contents <modules>
* :ref:`modindex`
* :ref:`genindex`
* :ref:`search`
.. highlight:: shell
.. _requirements:
===============================================
Requirements for yunguanfu-mil3id2019
===============================================
This is the software requirements file for yunguanfu-mil3id2019, part of the
SNAPPY project. The requirements listed below should define
what yunguanfu-mil3id2019 does. Each requirement can be matched to a unit test that
checks whether the requirement is met.
Requirements
~~~~~~~~~~~~
+------------+--------------------------------------------------------+-------------------------------------+
| ID | Description | Test |
+============+========================================================+=====================================+
| 0000 | Module has a help page | pylint, see |
| | | tests/pylint.rc and tox.ini |
+------------+--------------------------------------------------------+-------------------------------------+
| 0001 | Functions are documented | pylint, see |
| | | tests/pylint.rc and tox.ini |
+------------+--------------------------------------------------------+-------------------------------------+
| 0002 | Package has a version number | No test yet, handled by git. |
+------------+--------------------------------------------------------+-------------------------------------+
body {
font-family: "Helvetica", sans-serif;
letter-spacing: 0.02em;
line-height: 23px;
}
input,
button,
select,
textarea {
font-family: "Helvetica", sans-serif;
}
h1, h2 {
clear: left;
}
h1 {
font-size: 28px;
line-height: 36px;
}
h2 {
font-size: 22px;
line-height: 30px;
}
# This file lists the python packages that your software depends on
# for development.
# It is used by pip to manage software dependencies. It is not to be
# confused with the software requirements, which are listed in
# doc/requirements.rst
-r requirements.txt
coverage
mock
pyfakefs
parameterized
pylint
sphinx
sphinx_rtd_theme
pyinstaller
pytest
tox
# This file lists the python packages that your software depends on.
# It is used by pip to manage software dependencies. It is not to be
# confused with the software requirements, which are listed in
# doc/requirements.rst
numpy
[bdist_wheel]
universal=1
[versioneer]
VCS = git
style = pep440