Merge pull request #37 from tomalrussell/docs/developer

Docs/developer

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: e626cd57090d8df0be21e4df0f4e55cc3511d6ab
+    sha: a11d9314b22d8f8c7556443875b731ef05965464
     hooks:
     -   id: trailing-whitespace
     -   id: check-added-large-files

CONTRIBUTING.rst

@@ -0,0 +1,19 @@
+=================
+How to contribute
+=================
+
+🎉👍 First things first, thank you for considering contributing to `smif`
+
+Getting started
+---------------
+
+Please `raise an issue`_ for bugs spotted and features proposed.
+
+Github `pull requests`_ can be made against the master branch so long as we
+continue prototyping before a v1.0 release.
+
+See the `developer documentation`_ for details of testing and other conventions.
+
+.. _developer documentation: http://smif.readthedocs.io/en/latest/
+.. _pull requests: https://help.github.com/articles/about-pull-requests/
+.. _raise an issue: https://github.com/nismod/smif/issues

docs/contributing.rst

@@ -0,0 +1,2 @@
+.. _contributing:
+.. include:: ../CONTRIBUTING.rst

docs/developers.rst

@@ -0,0 +1,51 @@
+.. _developers:
+
+Developing `smif`
+=================
+
+*smif* is under active development at `github.com/nismod/smif`_
+
+
+Testing
+-------
+
+We use _pytest for testing, with tests under :code:`tests/` matching the module
+and class structure of :code:`smif/`.
+
+Install requirements for testing::
+
+    pip install -r test-requirements.txt
+
+
+Run tests::
+
+    python setup.py test
+
+
+Versioning
+----------
+
+:code:`smif` is currently pre-1.0, so API and usage are liable to change. After
+releasing a first major version, we intend to follow `semantic versioning`_, with
+major versions for any incompatible changes to the public API.
+
+
+Conventions
+-----------
+
+The numpydoc_ docstring conventions are used for inline documentation, which
+is used to generate the module reference documentation visible at readthedocs_
+and which can also be generated by running :code:`python setup.py build_sphinx`
+
+Linting is handled by `pre-commit`_ hooks, which can be installed from the root
+of the repository using::
+
+    pre-commit install
+
+
+.. _github.com/nismod/smif: https://github.com/nismod/smif
+.. _pytest: http://doc.pytest.org/en/latest/
+.. _semantic versioning: http://semver.org/
+.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+.. _readthedocs: http://smif.readthedocs.io/en/latest/api/smif.html
+.. _pre-commit: http://pre-commit.com/

docs/index.rst

@@ -8,6 +8,8 @@ Contents
 
    Getting Started <getting_started>
    Concept <concept>
+   Developing `smif` <developers>
+   Contributing <contributing>
    License <license>
    Authors <authors>
    Changelog <changes>