Doc: Move sample workflow out of the main document

encukou · web-flow · commit e5e34fcca748 · 2017-12-11T16:08:59.000+01:00
The Contributing docs were too long to read. Move the longness out, which should emphasize you'll be fine with the usual Git workflows. python-ldap#115
diff --git a/Doc/contributing.rst b/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:
diff --git a/Doc/sample_workflow.rst b/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.
