Add a demo walk-through to the coder guide

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

diff --git a/doc/source/coder.rst b/doc/source/coder.rst
index 0487cb8..4e956a2 100644 (file)
--- a/doc/source/coder.rst
+++ b/doc/source/coder.rst
@@ -2,7 +2,7 @@
  coder guide
 =============
 
  coder guide
 =============
 

-.. Copyright (c) 2004-2018 mudpy authors. Permission to use, copy,
+.. Copyright (c) 2004-2019 mudpy authors. Permission to use, copy,

    modify, and distribute this software is granted under terms
    provided in the LICENSE file distributed with this software.
 
    modify, and distribute this software is granted under terms
    provided in the LICENSE file distributed with this software.
 


@@ -43,15 +43,17 @@ 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
 :file:`setup.cfg`) and a recent release of the tox_ utility (at least
 Linux), a modern Python 3 interpreter (any of the minor revisions
 mentioned in the ``metadata.classifier`` section of
 :file:`setup.cfg`) and a recent release of the tox_ utility (at least

-the ``tox.minversion`` mentioned in :file:`tox.ini`).
+the ``tox.minversion`` mentioned in :file:`tox.ini`). The tox-venv_
+plug-in for tox is also recommended.

 
 .. _tox: https://tox.readthedocs.io/
 
 .. _tox: https://tox.readthedocs.io/

+.. _tox-venv: https://pypi.org/project/tox-venv/

 
 application program interface
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 application program interface
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-API documentation is maintained within docstrings in the mudpy source
-code.
+The :doc:`api` API documentation is maintained within docstrings in
+the mudpy source code.

 
 regression testing
 ~~~~~~~~~~~~~~~~~~
 
 regression testing
 ~~~~~~~~~~~~~~~~~~


@@ -77,3 +79,62 @@ new patches with the flake8_ utility should be performed with ``tox
 
 .. _Style Guide: :pep:`0008`
 .. _flake8: https://pypi.org/project/flake8
 
 .. _Style Guide: :pep:`0008`
 .. _flake8: https://pypi.org/project/flake8

+
+test and demo walk-through
+--------------------------
+
+The included tox configuration provides testenv definitions for a
+variety of analyzers, regression tests, documentation builds and
+package generation. It also has a ``demo`` testenv which will run the
+server using the provided :file:`etc/mudpy.conf` and other sample
+files. By default it listens on TCP port 4000 at the IPv6 loopback
+address, streams its logging to the terminal via stdout, and grants
+administrative rights automatically to an account named ``admin``
+(once created).
+
+Because all the dependencies besides the ``python3`` interpreter itself
+are available from PyPI, installing them should be fairly similar
+across most GNU/Linux distributions. For example, on Debian 10 (a.k.a.
+"Buster") you need to expressly install the ``pip`` and ``venv`` modules
+since they're packaged separately from the rest of the Python standard
+library. Once that's done, you can perform local installs of ``tox`` and
+``tox-venv`` as a normal non-root user. We're also going to install
+system packages for the ``git`` revision control toolset and an
+extensible console-based MUD client called ``tf5`` (TinyFugue version
+5)::
+
+    sudo apt install git python3-pip python3-venv tf5
+    pip install --user tox tox-venv
+    exit
+
+The reason for exiting is that, if this is the first time you've ever
+used pip's ``--user`` option, when you log back in your ``~/.profile``
+should see that there's now a ``~/.local/bin`` directory and add it to
+your ``$PATH`` environment variable automatically from that point on.
+Next, retrieve the project source code and switch your current working
+directory to where you've cloned it::
+
+    git clone https://mudpy.org/code/mudpy
+    cd mudpy
+
+Now you should be able to invoke any tox testenv you like. Just
+running ``tox`` without any additional options will go through the
+defalt battery of checks and is a good way to make sure everything is
+installed and working. Once you're ready to try out the server
+interactively, launch it like this::
+
+    tox -e demo
+
+Now in another terminal/session (because the one you've been using is
+busy displaying the server's logs) connect using a MUD client::
+
+    tf5 ip6-localhost 4000
+
+Log in as ``admin`` creating an account and then an avatar and awaken
+it. Try out the ``help`` command and make sure you see some command
+words in red (you're using a color terminal, right?) since those are
+admin-only commands and being able to see them confirms you're an
+administrator. When you're ready to terminate the service you can
+either give the ``halt`` command in your MUD client terminal or press
+the ``control`` and ``c`` keys together in the terminal where you ran
+tox. To exit the MUD client, give it the ``/quit`` command.