Commit f81ccbdc authored by Matt Clarkson's avatar Matt Clarkson

Initial commit.

parents
[run]
omit =
./sksurgerycore/_version.py
./sksurgerycore/__init__.py
./sksurgerycore/__main__.py
\ No newline at end of file
sksurgerycore/_version.py export-subst
# Pycharm
/.idea
# Generated files
.tox
.coverage
*.pyc
.pytest_cache/
# PyInstaller
build/
dist/
stages:
- build
- installer
- test
- deploy
build docs:
stage: build
script:
- tox -e docs
tags:
- shared-linux
artifacts:
paths:
- doc/
expire_in: 1 week
build linux installer:
stage: build
script:
- tox -e installer
tags:
- shared-linux
artifacts:
paths:
- dist/
expire_in: 1 week
build mac installer:
stage: build
script:
- tox -e installer
tags:
- shared-mac
artifacts:
paths:
- dist/
expire_in: 1 week
build windows installer:
stage: build
script:
- tox -e installer
tags:
- shared-win
artifacts:
paths:
- dist/
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
deploy docs to staging:
stage: deploy
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/scikit-surgerycore 2>&1
tags:
- docs-staging
environment:
name: staging
url: http://weisslab-lin.cs.ucl.ac.uk/staging/WEISS/SoftwareRepositories/scikit-surgerycore
only:
- master
dependencies:
- build docs
deploy docs to production:
stage: deploy
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/scikit-surgerycore 2>&1
tags:
- docs-production
environment:
name: production
only:
- public
dependencies:
- build docs
.. highlight:: shell
===============================================
Contributing to scikit-surgerycore
===============================================
We welcome contributions to scikit-surgerycore.
Reporting bugs and feature requests
-----------------------------------
Please create a new issue on https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/issues/new
When reporting a bug, please include:
* The version of scikit-surgerycore 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/scikit-surgerycore/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/scikit-surgerycore/issues/new
2. Read the design considerations below.
3. Fork the repository: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/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/scikit-surgerycore/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) 2018, 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 sksurgerycore/_version.py
scikit-surgerycore
===============================
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/raw/master/project-icon.png
:height: 128px
:width: 128px
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/badges/master/build.svg
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/pipelines
:alt: GitLab-CI test status
.. image:: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/badges/master/coverage.svg
:target: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/commits/master
:alt: Test coverage
.. image:: https://readthedocs.org/projects/scikit-surgerycore/badge/?version=latest
:target: http://scikit-surgerycore.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
scikit-surgerycore is a python project containing code to perform image guided surgery.
scikit-surgerycore is part of the `SNAPPY`_ software project, developed at the `Wellcome EPSRC Centre for Interventional and Surgical Sciences`_, part of `University College London (UCL)`_.
Installing
----------
You can pip install directly from the repository as follows:
::
pip install git+https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore
Developing
----------
Cloning
^^^^^^^
You can clone the repository using the following command:
::
git clone https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore
Running the tests
^^^^^^^^^^^^^^^^^
You can run the unit tests by installing and running tox:
::
pip install tox
tox
Contributing
^^^^^^^^^^^^
Please see the `contributing guidelines`_.
Useful links
^^^^^^^^^^^^
* `Source code repository`_
* `Documentation`_
Licensing and copyright
-----------------------
Copyright 2018 University College London.
scikit-surgerycore 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/scikit-surgerycore
.. _`Documentation`: https://scikit-surgerycore.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/scikit-surgerycore/blob/master/CONTRIBUTING.rst
.. _`license file`: https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore/blob/master/LICENSE
/sksurgerycore.rst
/sksurgerycore.*.rst
/modules.rst
/versioneer.rst
/build
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# scikit-surgerycore 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 sksurgerycore
modindex_common_prefix = [
'sksurgerycore.'
]
# General information about the project.
project = u'scikit-surgerycore'
copyright = u"2018, 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 = sksurgerycore.__version__
# The full version, including alpha/beta/rc tags.
# release = sksurgerycore.__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 = 'scikit-surgerycoredoc'
# -- 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', 'scikit-surgerycore.tex',
u'scikit-surgerycore 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', 'scikit-surgerycore',
u'scikit-surgerycore 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', 'scikit-surgerycore',
u'scikit-surgerycore Documentation',
u'Matt Clarkson',
'scikit-surgerycore',
'One line description of project.',
'Miscellaneous'),
]
.. include:: ../README.rst
Contents
~~~~~~~~
.. toctree::
:maxdepth: 1
requirements
pycharm
Module Contents <modules>
* :ref:`modindex`
* :ref:`genindex`
* :ref:`search`
.. _pycharm:
Some Hints for Developing with PyCharm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PyCharm is a popular python editor. This is a quickstart guide setting up
PyCharm for developing sksurgerycore.
This assumes you have PyCharm installed and configured to support virtual environments.
1. Start PyCharm
2. Select File > Open
3. Select the project's folder
4. Open in a new window
5. Open Preferences
6. Click on Project: [YourProject] and select Project Interpreter
7. At the right of the Project Interpreterm, click the cog
8. Select Add Local...
9. Select Virtual Environment
10. Choose a location for your virtual environment (for example, [YourHomeFolder]/VirtualEnvs/[YourProjectName])
11. Select a base interpreter (usually the latest version of Python 3).
12. Recommended settings: Do not inherit global site-packages, and do not make available to all projects.
13. Click OK
14. Click on Terminal
15. `pip install tox`
16. `tox`
17. Expand the project
18. Right-click on the Tests folder and choose "Run Unittests in tests". This will create a new configuration for running tests
19. Right-click on sksurgerycore and select Run sksurgerycore. This will create a new configuration for running the project.
20. Switch between the program and test configurations using the drop-down at the top of the screen, and the green arrow to run or the green bug to debug.
.. highlight:: shell
.. _requirements:
===============================================
Requirements for scikit-surgerycore
===============================================
This is the software requirements file for scikit-surgerycore, part of the
SNAPPY project. The requirements listed below should define
what scikit-surgerycore 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
six
[bdist_wheel]
universal=1
[versioneer]
VCS = git
style = pep440
versionfile_source = sksurgerycore/_version.py
tag_prefix = v
# coding=utf-8
"""
Setup for scikit-surgerycore
"""
from setuptools import setup, find_packages
import versioneer
# Get the long description
with open('README.rst') as f:
long_description = f.read()
setup(
name='scikit-surgerycore',
version=versioneer.get_version(),
cmdclass=versioneer.get_cmdclass(),
description='scikit-surgerycore',
long_description=long_description,
url='https://weisslab.cs.ucl.ac.uk/WEISS/SoftwareRepositories/scikit-surgerycore',
author='Matt Clarkson',
author_email='YOUR-EMAIL@ucl.ac.uk',
license='BSD-3 license',
classifiers=[
'Development Status :: 3 - Alpha',
'Intended Audience :: Developers',
'Intended Audience :: Healthcare Industry',
'Intended Audience :: Information Technology',
'Intended Audience :: Science/Research',
'License :: OSI Approved :: BSD License',
'Programming Language :: Python',
'Programming Language :: Python :: 2',
'Programming Language :: Python :: 3',
'Topic :: Scientific/Engineering :: Information Analysis',
'Topic :: Scientific/Engineering :: Medical Science Apps.',
],
keywords='medical imaging',
packages=find_packages(
exclude=[