Modernize coder documentation

[mudpy.git] / doc / source / coder.rst

diff --git a/doc/source/coder.rst b/doc/source/coder.rst
index e7e3817..7f4ddc8 100644 (file)
--- a/doc/source/coder.rst
+++ b/doc/source/coder.rst
@@ -2,7 +2,7 @@
  coder guide
 =============
 
-:Copyright: (c) 2004-2014 Jeremy Stanley <fungi@yuggoth.org>. Permission
+:Copyright: (c) 2004-2017 Jeremy Stanley <fungi@yuggoth.org>. Permission
             to use, copy, modify, and distribute this software is
             granted under terms provided in the LICENSE file distributed
             with this software.
@@ -35,15 +35,28 @@ A Gitweb_ interface is available, to make the change history easier to
 browse. This is found at http://mudpy.org/gitweb/mudpy/ and should be
 fairly self-explanatory.
 
-A GNU-format_ ChangeLog file is generated automatically from repository
-commit logs, available at http://mudpy.org/res/src/mudpy/doc/ChangeLog
-and is included in the doc directory of all tarball/zip files. The
-export script, git2gch, is included in the bin directory.
+A ChangeLog file is generated automatically from repository commit
+logs, and is included automatically in all sdist_ tarballs. It can
+be regenerated easily by running `tox -e venv python setup.py sdist`
+from the top level directory of the Git repository in a working
+`developer environment`_.
 
 .. _Git: http://git-scm.com/
 .. _Gitweb: http://git.wiki.kernel.org/index.php/Gitweb
-.. _GNU-format: http://www.gnu.org/prep/standards/html_node
-                /Style-of-Change-Logs.html#Style-of-Change-Logs
+.. _sdist: https://packaging.python.org/glossary
+           /#term-source-distribution-or-sdist
+
+developer environment
+---------------------
+
+Basic developer requirements are a POSIX Unix derivative (such as
+Linux), a modern Python 3 interpreter (any of the minor revisions
+mentioned in the ``metadata.classifier`` section of setup.cfg_) and
+a recent release of the tox_ utility (at least the
+``tox.minversion`` mentioned in tox.ini_).
+
+.. _setup.cfg: http://mudpy.org/gitweb?p=mudpy.git;a=blob;f=setup.cfg
+.. _tox.ini: http://mudpy.org/gitweb?p=mudpy.git;a=blob;f=tox.ini
 
 application program interface
 -----------------------------
@@ -54,11 +67,14 @@ code.
 regression testing
 ------------------
 
-All new commits are tested using a regression testing script in the bin
-directory of the source archive, to help ensure the software is
-continually usable. Any new features should be accompanied by suitable
-regression tests so that their functionality can be maintained properly
-through future releases.
+All new commits are tested using a selftest script in the
+``mudpy/tests`` directory of the source archive, to help ensure the
+software is continually usable. Any new features should be
+accompanied by suitable regression tests so that their functionality
+can be maintained properly through future releases. The selftest can
+be invoked with ``tox -e selftest`` after starting the daemon with
+the test configuration provided in the ``mudpy/tests/fixtures``
+directory.
 
 -------
  style
@@ -68,9 +84,8 @@ This project follows Guido van Rossum and Barry Warsaw's `Style Guide`_
 for Python Code (a.k.a. "PEP-8"). When in need of sample code or other
 examples, any common source code file or text document file distributed
 as part of mudpy should serve as a suitable reference. Testing of all
-new patches with the flake8_ and pylint_ utilities is also highly
-recommended.
+new patches with the flake8_ utility should be performed with ``tox
+-e flake8`` to ensure adherence to preferred style conventions.
 
 .. _Style Guide: http://www.python.org/dev/peps/pep-0008/
 .. _flake8: https://pypi.python.org/pypi/flake8
-.. _pylint: https://pypi.python.org/pypi/pylint