X-Git-Url: https://mudpy.org/gitweb?p=mudpy.git;a=blobdiff_plain;f=doc%2Fsource%2Fcoder.rst;h=4e956a216824810bfd8db34383b057a07af56540;hp=80edcf8fd966f2ceb84e4286733cadd07c1e34cb;hb=16fafebe85897b37e1c0f15a6cc11eeaede1c48d;hpb=2106d9ea9f4f889c9ef2bbe83635379087a3dacf diff --git a/doc/source/coder.rst b/doc/source/coder.rst index 80edcf8..4e956a2 100644 --- a/doc/source/coder.rst +++ b/doc/source/coder.rst @@ -2,10 +2,9 @@ coder guide ============= -.. Copyright (c) 2004-2018 Jeremy Stanley . - Permission to use, copy, modify, and distribute this software is - granted under terms provided in the LICENSE file distributed with - this software. +.. 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. This guide attempts to embody a rudimentary set of rules for developer submissions of source code and documentation targeted for inclusion @@ -21,24 +20,19 @@ documented, and contributions to that end are heartily welcomed. version control system ~~~~~~~~~~~~~~~~~~~~~~ -Git_ is used for version control on the project, and the archive can be -cloned anonymously from http://mudpy.org/git/mudpy if desired. For now, -detailed commits can be E-mailed to fungi@yuggoth.org, but there will -most likely be a developer mailing list for more open presentation and -discussion of patches soon. +Git_ is used for version control on the project, and the archive can +be browsed or cloned anonymously from https://mudpy.org/code/mudpy . +For now, detailed commits can be E-mailed to fungi@yuggoth.org, but +there will most likely be a developer mailing list for more open +presentation and discussion of patches soon. -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 :file:`ChangeLog` is generated automatically from repository +commit logs, and is included automatically in all sdist_ tarballs. It +can be regenerated easily by running :command:`tox -e dist` from the +top level directory of the Git repository in a working `developer +environment`_. -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 +.. _Git: https://git-scm.com/ .. _sdist: https://packaging.python.org/glossary /#term-source-distribution-or-sdist @@ -47,18 +41,19 @@ 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_). +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-venv_ +plug-in for tox is also recommended. -.. _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 +.. _tox: https://tox.readthedocs.io/ +.. _tox-venv: https://pypi.org/project/tox-venv/ 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 ~~~~~~~~~~~~~~~~~~ @@ -82,5 +77,64 @@ as part of mudpy should serve as a suitable reference. Testing of all 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 +.. _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.