Add initial testing guide

README.rst

@@ -36,6 +36,8 @@ pylibssh: Python bindings to client functionality of libssh specific to Ansible
 Nightlies @ Dumb PyPI @ GitHub Pages
 ------------------------------------
 
+.. DO-NOT-REMOVE-nightlies-START
+
 We publish nightlies on tags and pushes to devel.
 They are hosted on a GitHub Pages based index generated
 by `dumb-pypi <https://pypi.org/project/dumb-pypi/>`_.
@@ -49,6 +51,8 @@ The web view is @ https://ansible.github.io/pylibssh/.
         --pre \
         ansible-pylibssh
 
+.. DO-NOT-REMOVE-nightlies-END
+
 
 Requirements
 ------------

docs/conf.py

@@ -58,6 +58,9 @@
 default_role = 'any'
 
 nitpicky = True
+nitpick_ignore = [
+    ('envvar', 'PATH'),
+]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -146,6 +149,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'cython': ('https://cython.readthedocs.io/en/latest', None),
+    'pip': ('https://pip.pypa.io/en/latest', None),
     'python': ('https://docs.python.org/3', None),
     'python2': ('https://docs.python.org/2', None),
 }

docs/contributing/guidelines.rst

@@ -1,5 +1,10 @@
 .. include:: ../../.github/CONTRIBUTING.rst
 
+.. seealso::
+
+   :ref:`Testing Guide`
+       Running the tests suite locally
+
 -----------------
 Contributing docs
 -----------------

docs/contributing/testing_guide.rst

@@ -0,0 +1,145 @@
+*************
+Testing Guide
+*************
+
+Welcome to the |project| Testing Guide!
+
+This page contains information on how to test |project|
+locally as well as some notes of how the automated testing and linting is implemented.
+
+
+Mandatory tooling
+=================
+
+All build and test processes use tox_-centric workflow. So
+first of all, let's install it:
+
+.. code-block:: shell-session
+
+    $ python -m pip install 'tox >= 3.19.0' --user
+
+.. note::
+
+    This will install tox_ in :doc:`user-global
+    site-packages <pip:user_guide>`. To make it
+    discoverable, you may need to add :command:`export
+    PATH="$HOME/.local/bin:$PATH"` to your :file:`~/.bashrc`
+    or :file:`~/.zshrc`.
+
+    The examples below will use the :py:mod:`python:runpy`
+    syntax (CLI option :option:`python:-m`) to avoid the
+    need to put scripts into the search :envvar:`PATH`.
+
+.. tip::
+
+    While the example above uses pip, alternatively you may
+    install tox_ via your OS package manager (e.g.
+    :program:`apt`, :program:`dnf`, :program:`emerge`,
+    :program:`packman`, :program:`yum`, :program:`zypper`
+    etc.).
+
+    It is important to have at least `version 3.8.0 <tox
+    v3.8.0_>`_ because it'll allow tox_ to auto-provison a
+    newer version of itself just for |project|.
+
+Tox_ will take care of the Python dependencies but it's up
+to you to make the external ecosystem dependencies available.
+
+|project|'s core dependency is  libssh_. |project| links
+against it and so the development headers must be present
+on your system for build to succeed.
+
+The next external build-time dependency is `Cython
+<cython:index>` and `using it
+<cython:src/quickstart/install>` requires presense of GCC_.
+Consult with your OS's docs to figure out how to get it onto
+your machine.
+
+.. _GCC: https://gcc.gnu.org
+.. _libssh: https://libssh.org
+.. _tox: https://tox.readthedocs.io
+.. _tox v3.8.0:
+   https://tox.readthedocs.io/en/latest/changelog.html#v3-8-0-2019-03-27
+
+Getting the source code
+=======================
+
+Once you sort out the toolchain, get |project|'s source:
+
+.. code-block:: shell-session
+
+    $ git clone https://github.com/ansible/pylibssh.git ~/src/github/ansible/pylibssh
+    $ # or, if you use SSH:
+    $ git clone [email protected]:ansible/pylibssh.git ~/src/github/ansible/pylibssh
+    $ cd ~/src/github/ansible/pylibssh
+    [dir:pylibssh] $
+
+.. attention::
+
+    All following commands assume the working dir to be the
+    Git checkout folder (\
+    :file:`~/src/github/ansible/pylibssh` in the example)
+
+Running tests
+==============
+
+To run tests under your current Python interpreter, run:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ python -m tox
+
+If you want to target some other Python version, do:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ python -m tox -e py38
+
+Continuous integration
+^^^^^^^^^^^^^^^^^^^^^^
+
+In the CI, the testing is done slightly differently. First,
+the Python package distributions are built with:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ python -m tox -e build-dists
+
+Then, they are tested in a matrix of separate jobs across
+different OS and CPython version combinations:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ python -m tox -e test-binary-dists
+
+Quality and sanity
+^^^^^^^^^^^^^^^^^^
+
+Additionally, there's a separate workflow that runs linting\
+-related checks that can be reproduced locally as follows:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ python -m tox -e build-docs  # Sphinx docs build
+    [dir:pylibssh] $ python -m tox -e lint  # pre-commit.com tool
+
+Continuous delivery
+^^^^^^^^^^^^^^^^^^^
+
+Besides testing and linting, |project| also has `GitHub
+Actions workflows CI/CD`_ set up to publish those same
+Python package distributions **after** they've been tested.
+
+Commits from ``devel`` get published to
+https://test.pypi.org/project/ansible-pylibssh/ and tagged
+commits are published to
+https://pypi.org/project/ansible-pylibssh/.
+
+Besides, if you want to test your project against unreleased
+versions of |project|, you may want to go for nightlies.
+
+.. include:: ../../README.rst
+   :start-after: DO-NOT-REMOVE-nightlies-START
+   :end-before: DO-NOT-REMOVE-nightlies-END
+
+.. _GitHub Actions workflows CI/CD: https://github.com/features/actions

docs/index.rst

@@ -29,6 +29,7 @@ Welcome to |project|'s documentation!
    contributing/code_of_conduct
    contributing/guidelines
    contributing/security
+   contributing/testing_guide