From 4b520dd4bf1981b625bd46571109f314b69d562c Mon Sep 17 00:00:00 2001
From: Paul McCarthy <pauld.mccarthy@gmail.com>
Date: Tue, 25 Apr 2017 14:33:58 +0100
Subject: [PATCH] Formatting
---
doc/contributing.rst | 103 +++++++++++++++++++++++--------------------
1 file changed, 55 insertions(+), 48 deletions(-)
diff --git a/doc/contributing.rst b/doc/contributing.rst
index 7803bffc4..81c6fb5d0 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -1,5 +1,5 @@
-Contributing to fslpy
-=====================
+Contributing to ``fslpy``
+=========================
*This document is a work in progress*
@@ -9,87 +9,94 @@ Development model
-----------------
- - The master branch should always be stable and ready to release. All
- development occurs on the master branch.
+- The master branch should always be stable and ready to release. All
+ development occurs on the master branch.
- - All changes to the master branch occur via merge requests. Individual
- developers are free to choose their own development workflow in their own
- repositories.
+- All changes to the master branch occur via merge requests. Individual
+ developers are free to choose their own development workflow in their own
+ repositories.
- - A separate branch is created for each release. Hotfixes may be added to
- these release branches.
+- A separate branch is created for each release. Hotfixes may be added to
+ these release branches.
- - Merge requests will not be accepted unless:
+- Merge requests will not be accepted unless:
- - All existing tests pass (or have been updated as needed).
- - New tests have been written to cover newly added features.
- - Code coverage is as close to 100% as possible.
- - Coding conventions are adhered to (unless there is good reason not to).
+ - All existing tests pass (or have been updated as needed).
+ - New tests have been written to cover newly added features.
+ - Code coverage is as close to 100% as possible.
+ - Coding conventions are adhered to (unless there is good reason not to).
Version number
--------------
-The `fslpy` version number follows [semantic versioning](http://semver.org/)
-rules, so that dependant projects are able to perform compatibility testing.
-The version number comprises three numbers::
+The ``fslpy`` version number follows `semantic versioning
+<http://semver.org/>`_ rules, so that dependant projects are able to perform
+compatibility testing. The full version number string consists of three
+numbers::
major.minor.patch
- - The `patch` number is incremented on bugfixes and minor
- (backwards-compatible) changes.
+- The ``patch`` number is incremented on bugfixes and minor
+ (backwards-compatible) changes.
- - The `minor` number is incremented on feature additions and major
- backwards-compatible changes.
+- The ``minor`` number is incremented on feature additions and/or
+ backwards-compatible changes.
- - The `major` number is incremented on backwards-incompatible changes.
+- The ``major`` number is incremented on major feature additions, and
+ backwards-incompatible changes.
Testing
-------
-Unit and integration tests are currently run with `py.test` and `coverage`. We
-don't have CI configured yet, so tests have to be run manually.
+Unit and integration tests are currently run with ``py.test`` and
+``coverage``. We don't have CI configured yet, so tests have to be run
+manually.
- - Aim for 100% code coverage.
- - Tests must pass on both python 2.7 and 3.5
- - Tests must pass on both wxPython 3.0.2.0 and 4.0.0
+- Aim for 100% code coverage.
+- Tests must pass on both python 2.7 and 3.5
+- Tests must pass on both wxPython 3.0.2.0 and 4.0.0
Coding conventions
------------------
- - Clean, readable code is good
- - White space and visual alignment is good (where it helps to make the code
- more readable)
- - Clear and accurate documentation is good
+- Clean, readable code is good
+- White space and visual alignment is good (where it helps to make the code
+ more readable)
+- Clear and accurate documentation is good
+- Document all modules, functions, classes, and methods using
+ `ReStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_.
Configure your text editor to use:
- - [flake8](http://flake8.pycqa.org/en/latest/): This checks your code for adherence
- to the [PEP8](https://www.python.org/dev/peps/pep-0008/) coding standard.
+- `flake8 <http://flake8.pycqa.org/en/latest/>`_: This checks your code for
+ adherence to the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ coding
+ standard.
- - [pylint](https://www.pylint.org/): This checks that your code follows other
- good conventions.
+- `pylint <https://www.pylint.org/>`_: This checks that your code follows
+ other good conventions.
+
Because I like whitespace and vertical alignment more than PEP8 does, the
following violations of the PEP8 standard are accepted (see
-[here](https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes)
+`here <https://pycodestyle.readthedocs.io/en/latest/intro.html#error-codes>`_
for a list of error codes):
- - E127: continuation line over-indented for visual indent
- - E201: whitespace after '('
- - E203: whitespace before ':'
- - E221: multiple spaces before operator
- - E222: multiple spaces after operator
- - E241: multiple spaces after ','
- - E271: multiple spaces after keyword
- - E272: multiple spaces before keyword
- - E301: expected 1 blank line, found 0
- - E302: expected 2 blank lines, found 0
- - E303: too many blank lines (3)
- - E701: multiple statements on one line (colon)
+- E127: continuation line over-indented for visual indent
+- E201: whitespace after '('
+- E203: whitespace before ':'
+- E221: multiple spaces before operator
+- E222: multiple spaces after operator
+- E241: multiple spaces after ','
+- E271: multiple spaces after keyword
+- E272: multiple spaces before keyword
+- E301: expected 1 blank line, found 0
+- E302: expected 2 blank lines, found 0
+- E303: too many blank lines (3)
+- E701: multiple statements on one line (colon)
--
GitLab