From: Jeremy Stanley Date: Mon, 17 Apr 2017 16:46:27 +0000 (+0000) Subject: Modernize coder documentation X-Git-Tag: 0.0.1~164 X-Git-Url: https://mudpy.org/gitweb?a=commitdiff_plain;h=81ebb2a9ec44df86faf97d3236ca59d0f5709b2a;p=mudpy.git Modernize coder documentation Update the coder docs to remove obsolete references to the old git2gch script, include new information on testing expectations and outline a recommended tox-based developer environment and workflow. --- diff --git a/doc/source/coder.rst b/doc/source/coder.rst index e7e3817..7f4ddc8 100644 --- a/doc/source/coder.rst +++ b/doc/source/coder.rst @@ -2,7 +2,7 @@ coder guide ============= -:Copyright: (c) 2004-2014 Jeremy Stanley . Permission +:Copyright: (c) 2004-2017 Jeremy Stanley . 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