From 16fafebe85897b37e1c0f15a6cc11eeaede1c48d Mon Sep 17 00:00:00 2001 From: Jeremy Stanley Date: Sun, 7 Jul 2019 01:49:28 +0000 Subject: [PATCH] Add a demo walk-through to the coder guide Include an example of a simple development environment setup, explaining how to start the server using the provided sample configuration and then interact with it using a console-based MUD client. --- doc/source/coder.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/doc/source/coder.rst b/doc/source/coder.rst index 25493b0..4e956a2 100644 --- a/doc/source/coder.rst +++ b/doc/source/coder.rst @@ -79,3 +79,62 @@ new patches with the flake8_ utility should be performed with ``tox .. _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. -- 2.11.0