- revamping package documentation

README.rst

@@ -1,5 +1,5 @@
-.. image:: https://travis-ci.com/dataflake/dataflake.wsgi.cheroot.svg?branch=master
-   :target: https://travis-ci.com/dataflake/dataflake.wsgi.cheroot
+.. image:: https://github.com/dataflake/dataflake.wsgi.cheroot/actions/workflows/tests.yml/badge.svg
+   :target: https://github.com/dataflake/dataflake.wsgi.cheroot/actions/workflows/tests.yml
 
 .. image:: https://coveralls.io/repos/github/dataflake/dataflake.wsgi.cheroot/badge.svg?branch=master
    :target: https://coveralls.io/github/dataflake/dataflake.wsgi.cheroot?branch=master
@@ -17,8 +17,9 @@
    :alt: Supported Python versions
 
 
-dataflake.wsgi.cheroot
-======================
+========================
+ dataflake.wsgi.cheroot
+========================
 
 This package provides a PasteDeploy-compatible entry point to easily integrate
 the `cheroot WSGI server <https://github.com/cherrypy/cheroot>`_ into an

buildout.cfg

@@ -1,11 +1,10 @@
 [buildout]
 extends =
-    https://zopefoundation.github.io/Zope/releases/master/versions.cfg
+    https://zopefoundation.github.io/Zope/releases/master/versions-prod.cfg
 develop = .
 parts =
     test
     scripts
-    docs
 
 
 [test]
@@ -20,11 +19,3 @@ eggs =
     dataflake.wsgi.cheroot
 scripts =
     mkcherootinstance
-
-[docs]
-recipe = zc.recipe.egg
-eggs =
-    dataflake.wsgi.cheroot[docs]
-    Sphinx
-scripts =
-    sphinx-build

docs/development.rst

@@ -1,49 +1,66 @@
 Development
 ===========
 
-.. highlight:: console
+Bug tracker
+-----------
+For bug reports, suggestions or questions please use the
+GitHub issue tracker at
+https://github.com/dataflake/dataflake.wsgi.cheroot/issues.
+
 
 Getting the source code
 -----------------------
-The source code is maintained on GitHub::
+The source code is maintained on GitHub. To check out the main branch:
+
+.. code-block:: console
 
   $ git clone https://github.com/dataflake/dataflake.wsgi.cheroot.git
 
+You can also browse the code online at
+https://github.com/dataflake/dataflake.wsgi.cheroot
 
-Setting up a development sandbox and testing
---------------------------------------------
-Once you've obtained a source checkout, you can follow these instructions to
-perform various development tasks.  All development requires that you run the
-buildout from the package root directory::
 
-  $ python2.7 bootstrap.py
-  $ bin/buildout
+Preparing the development sandbox
+---------------------------------
+The following steps only need to be done once to install all the tools and
+scripts needed for building, packaging and testing. First, create a
+:term:`Virtual environment`. The example here uses Python 3.11, but any Python
+version supported by this package will work. Then install all the required
+tools:
 
-Once you have a buildout, the tests can be run as follows::
+.. code-block:: console
 
-  $ bin/test
+    $ cd dataflake.wsgi.cheroot
+    $ python3.11 -m venv .
+    $ bin/pip install -U pip wheel
+    $ bin/pip install -U setuptools zc.buildout tox twine
 
 
-Building the documentation
---------------------------
-The Sphinx documentation is built by doing the following from the
-directory containing setup.py::
+Running the tests
+-----------------
+You can use ``tox`` to run the unit and integration tests in this package. The
+shipped ``tox`` configuration can run the tests for all supported platforms.
+You can read the entire long list of possible options on the
+`tox CLI interface documentation page
+<https://tox.wiki/en/latest/cli_interface.html>`_, but the following examples
+will get you started:
 
-  $ cd docs
-  $ make html
+.. code-block:: console
 
-The finished HTML files are under `docs/_build/html`.
+    $ bin/tox -l       # List all available environments
+    $ bin/tox -pall    # Run tests for all environments in parallel
+    $ bin/tox -epy311  # Run tests on Python 3.11 only
+    $ bin/tox -elint   # Run package sanity checks and lint the code
 
 
-Making a release
-----------------
-These instructions assume that you have a development sandbox set 
-up using :mod:`zc.buildout` as the scripts used here are generated 
-by the buildout::
+Building the documentation
+--------------------------
+``tox`` is also used to build the :term:`Sphinx`-based documentation. The
+input files are in the `docs` subfolder and the documentation build step will
+compile them to HTML. The output is stored in `docs/_build/html/`:
+
+.. code-block:: console
 
-  $ bin/buildout -N
-  $ bin/buildout setup setup.py sdist bdist_wheel
-  $ bin/twine upload -s dist/*
+    $ bin/tox -edocs
 
-The ``bin/buildout`` step will make sure the correct package information 
-is generated.
+If the documentation contains doctests they are run as well.

docs/glossary.rst

@@ -7,18 +7,32 @@ Glossary
 
 .. glossary::
 
+  Sphinx
+    The documentation for this package is maintained using
+    `Sphinx <https://www.sphinx-doc.org/>`_, a tool to create documentation
+    in many formats based on reStructuredText files.
+
+  virtual environment
+    The `Python venv module <https://docs.python.org/3/library/venv.html>`_
+    is used to create lightweight “virtual environments”, each with their
+    own independent set of Python packages installed in their site
+    directories. A virtual environment is created on top of an existing
+    Python installation, known as the virtual environment’s “base” Python,
+    and may optionally be isolated from the packages in the base environment,
+    so only those explicitly installed in the virtual environment are
+    available.
+
   WSGI
     Web Server Gateway Interface. It is a specification that describes how a
     web server communicates with web applications, and how web applications
     can be chained together to process one request.
     WSGI is a Python standard described in detail in
     `PEP 3333 <https://www.python.org/dev/peps/pep-3333/>`_.
 
-  Virtualenv
-    An isolated Python environment. Allows you to control which packages
-    are used on a particular project by cloning your main Python. virtualenv
-    was created by Ian Bicking.
+  zc.buildout
+    `zc.buildout <http://buildout.org>`_ is a Python-based build system
+    for creating, assembling and deploying applications.
 
   Zope
-    `The Z Object Publishing Framework <http://zope.org>`_.  The granddaddy 
-    of Python web frameworks.
+    `The Z Object Publishing Framework <https://www.zope.dev>`_.
+    The granddaddy of Python web frameworks.

docs/index.rst

@@ -1,17 +1,26 @@
 .. include:: ../README.rst
 
+
+Narrative documentation
+-----------------------
+Narrative documentation explaining how to use :mod:`dataflake.wsgi.cheroot`.
+
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   installation
-   usage
-   development
-   changes
+    installation
+    usage
+    development
+    changes
 
 
-Indices and tables
-==================
+Support
+-------
+If you need commercial support for this software package, please
+visit `https://www.zetwork.com <https://www.zetwork.com/>`_.
 
+
+Indices and tables
+------------------
 * :ref:`genindex`
-* :ref:`search`
 * :ref:`glossary`

docs/installation.rst

@@ -1,28 +1,21 @@
 Installation
 ============
-You will need `Python <http://python.org>`_ 2.7 or 3.5 and higher to install
-and use :mod:`dataflake.wsgi.cheroot`.
 
-It is advisable to install :mod:`dataflake.wsgi.cheroot` into a
-:term:`virtualenv` or similar environment like a buildout from
-:mod:`zc.buildout` to obtain isolation from any "system" packages you've got
-installed in your Python version (and likewise, to prevent
-:mod:`dataflake.wsgi.cheroot` from globally installing versions of packages
-that are not compatible with your system Python).
 
-Setuptools/Distutils::
+Install with ``pip``
+--------------------
 
-  $ easy_install dataflake.wsgi.cheroot
+.. code:: 
 
-Pip::
+    $ pip install dataflake.wsgi.cheroot
 
-  $ pip install dataflake.wsgi.cheroot
 
-If you use :mod:`zc.buildout` you can add :mod:`dataflake.wsgi.cheroot`
-to the necessary ``eggs`` section to have it pulled in automatically::
+Install with ``zc.buildout``
+----------------------------
+Just add :mod:`dataflake.wsgi.cheroot` to the ``eggs`` setting(s) in your
+buildout configuration to have it pulled in automatically::
 
     ...
     eggs =
         dataflake.wsgi.cheroot
     ...
-