Doc: Move sample workflow out of the main document

The Contributing docs were too long to read.
Move the longness out, which should emphasize you'll be fine with
the usual Git workflows.

https://github.com/python-ldap/python-ldap/pull/115

Doc/contributing.rst

@@ -8,6 +8,12 @@ If you'd like to contribute (be it code, documentation, maintenance effort,
 or anything else), this guide is for you.
 
 
+.. toctree::
+   :hidden:
+
+   sample_workflow.rst
+
+
 Communication
 =============
 
@@ -54,8 +60,8 @@ If required, write to coordinate a more secure channel.
 All other communication should be public.
 
 
-Process for Code contributions
-==============================
+Contributing code
+=================
 
 If you're used to open-source Python development with Git, here's the gist:
 
@@ -76,86 +82,7 @@ Or, if you prefer to avoid closed-source services:
 .. _Read the Docs: http://python-ldap.readthedocs.io/
 
 If you're new to some aspect of the project, you're welcome to use (or adapt)
-the workflow below.
-
-
-Sample workflow
----------------
-
-We assume that, as a user of python-ldap you're not new to software
-development in general, so these instructions are terse.
-If you need additional detail, please do ask on the mailing list.
-
-.. note::
-
-    The following instructions are for Linux.
-    If you can translate them to another system, please contribute your
-    translation!
-
-
-Install `Git`_ and `tox`_.
-
-Clone the repository::
-
-    $ git clone https://github.com/python-ldap/python-ldap
-    $ cd python-ldap
-
-Create a `virtual environment`_ to ensure you in-development python-ldap won't
-affect the rest of your system::
-
-    $ python3 -m venv __venv__
-
-(For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)
-
-.. _git: https://git-scm.com/
-.. _virtual environment: https://docs.python.org/3/library/venv.html
-.. _virtualenv: https://virtualenv.pypa.io/en/stable/
-
-Activate the virtual environment::
-
-    $ source __venv__/bin/activate
-
-Install python-ldap to it in `editable mode`_::
-
-    (__venv__)$ python -m pip install -e .
-
-This way, importing a Python module from python-ldap will directly
-use the code from your source tree.
-If you change C code, you will still need to recompile
-(using the ``pip install`` command again).
-
-.. _editable mode: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
-
-Change the code as desired.
-
-
-To run tests, install and run `tox`_::
-
-    (__venv__)$ python -m pip install tox
-    (__venv__)$ tox --skip-missing-interpreters
-
-This will run tests on all supported versions of Python that you have
-installed, skipping the ones you don't.
-To run a subset of test environments, run for example::
-
-    (__venv__)$ tox -e py27,py36
-
-In addition to ``pyXY`` environments, we have extra environments
-for checking things independent of the Python version:
-
-* ``doc`` checks syntax and spelling of the documentation
-* ``coverage-report`` generates a test coverage report for Python code.
-  It must be used last, e.g. ``tox -e py27,py36,coverage-report``.
-* ``py2-nosasltls`` and ``py3-nosasltls`` check functionality without
-  SASL and TLS bindings compiled in.
-
-
-When your change is ready, commit to Git, and submit a pull request on GitHub.
-You can take a look at the `committer instructions`_ to see what we are looking
-for in a pull request.
-
-If you don't want to open a GitHub account, please send patches as attachments
-to the python-ldap mailing list.
+our :ref:`sample workflow <sample workflow>`.
 
 
 .. _additional tests:

Doc/sample_workflow.rst

@@ -0,0 +1,85 @@
+
+.. _sample workflow:
+
+Sample workflow for python-ldap development
+-------------------------------------------
+
+This document will guide you through the process of contributing a change
+to python-ldap.
+
+We assume that, as a user of python-ldap, you're not new to software
+development in general, so these instructions are terse.
+If you need additional detail, please do ask on the mailing list.
+
+.. note::
+
+    The following instructions are for Linux.
+    If you can translate them to another system, please contribute your
+    translation!
+
+
+Install `Git`_, `tox`_ and the :ref:`build prerequisites`.
+
+.. _tox: https://tox.readthedocs.io/en/latest/
+
+Clone the repository::
+
+    $ git clone https://github.com/python-ldap/python-ldap
+    $ cd python-ldap
+
+Create a `virtual environment`_ to ensure you in-development python-ldap won't
+affect the rest of your system::
+
+    $ python3 -m venv __venv__
+
+(For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)
+
+.. _git: https://git-scm.com/
+.. _virtual environment: https://docs.python.org/3/library/venv.html
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+
+Activate the virtual environment::
+
+    $ source __venv__/bin/activate
+
+Install python-ldap to it in `editable mode`_::
+
+    (__venv__)$ python -m pip install -e .
+
+This way, importing a Python module from python-ldap will directly
+use the code from your source tree.
+If you change C code, you will still need to recompile
+(using the ``pip install`` command again).
+
+.. _editable mode: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
+
+Change the code as desired.
+
+
+To run tests, install and run `tox`_::
+
+    (__venv__)$ python -m pip install tox
+    (__venv__)$ tox --skip-missing-interpreters
+
+This will run tests on all supported versions of Python that you have
+installed, skipping the ones you don't.
+To run a subset of test environments, run for example::
+
+    (__venv__)$ tox -e py27,py36
+
+In addition to ``pyXY`` environments, we have extra environments
+for checking things independent of the Python version:
+
+* ``doc`` checks syntax and spelling of the documentation
+* ``coverage-report`` generates a test coverage report for Python code.
+  It must be used last, e.g. ``tox -e py27,py36,coverage-report``.
+* ``py2-nosasltls`` and ``py3-nosasltls`` check functionality without
+  SASL and TLS bindings compiled in.
+
+
+When your change is ready, commit to Git, and submit a pull request on GitHub.
+You can take a look at the :ref:`committer instructions` to see what we are looking
+for in a pull request.
+
+If you don't want to open a GitHub account, please send patches as attachments
+to the python-ldap mailing list.