Contributing¶
Code organisation¶
File paths¶
All file paths should be defined in cellfinder.tools.prep.Paths
. Any
intermediate file paths, (i.e. those which are not of interest to the typical
end user) should be prefixed with tmp__
. These should then be cleaned up as
soon as possible after generation.
Conventions¶
Cellfinder has recently (2019-08-02) dropped support for Python 3.5. Following this, a number of new python features will be adopted throughout.
pathlib conventions (rather then
os.path
).f-strings (rather than
.format()
or using the old%
operator).
In all cases, please aim to replace old calls to os.path
or .format()
with pathlib object methods and f-strings.
Travis¶
All commits & pull requests will be build by Travis.
To ensure there are no issues, please check that it builds: pip install .
and run all of the tests: pytest
before commiting changes. Some tests may
take a long time (e.g. those requiring tensorflow if you don’t have a GPU).
These tests should be marked with @pytest.mark.slow
, e.g.:
import pytest
@pytest.mark.slow
def test_something_slow():
slow_result = run_slow_processes()
assert slow_result == expected_slow_thing
During development, these “slow” tests can be skipped by running pytest -m "not slow"
.
Formatting¶
To ensure a consistent code style, please use
Black before commiting changes.
Please use the syntax: black ./ -l 79 --target-version py37
Documentation¶
Documentation is built using Sphinx with Markdown (rather than
reStructuredText). Please edit (or create new) .md
files in the appropriate
directory in cellfinder/doc_build
. The organisation of these files is then
defined in index.rst
.
Please ensure that:
Any new changes are added to the release notes (
doc_build/main/about/release_notes.md
)All command-line functions are fully documented, including an explanation of all arguments, and example syntax.
To build the documentation (assuming you installed cellfinder with
pip install -e .[dev]
to install the dependencies):
cd doc_build
make html
Prior to commmiting to master, ensure that contents of
doc_build/_build/html/
is copied to cellfinder/docs
for
hosting with github pages.
This can be done automatically with a pre-commit hook. An example is here.
Dependencies¶
Any dependencies in the master
branch will be checked by
dependabot, and a pull request will be generated to
update which are outdated. Please only merge these if all tests are passing,
and you are confident that there will be no issues.
Misc¶
Configuration files
Any configuration files that cellfinder edits with local information (e.g.
atlas installation location) should be in the .gitignore
file. Please ensure
that any custom files are not commited to the repository.