From 4128bc473358eadb58a0582fc10afdd7088a29dd Mon Sep 17 00:00:00 2001 From: Griatch Date: Thu, 10 Nov 2022 23:15:54 +0100 Subject: [PATCH] Rounds of doc cleanups --- docs/source/Components/Components-Overview.md | 3 +- docs/source/Contribs/Contrib-Menu-Login.md | 2 +- docs/source/Howtos/Howtos-Overview.md | 6 +- docs/source/Setup/Installation-Git.md | 3 +- .../Setup/Installation-Non-Interactive.md | 2 +- docs/source/Setup/Installation.md | 48 ++++------ docs/source/Setup/Setup-Overview.md | 3 +- docs/source/Setup/Start-Stop-Reload.md | 92 +++++++++---------- docs/source/index.md | 30 +++--- 9 files changed, 87 insertions(+), 102 deletions(-) diff --git a/docs/source/Components/Components-Overview.md b/docs/source/Components/Components-Overview.md index 0f0e93d248..a0cc25688b 100644 --- a/docs/source/Components/Components-Overview.md +++ b/docs/source/Components/Components-Overview.md @@ -1,7 +1,6 @@ # Core Components -These are the 'building blocks' out of which Evennia is built. This documentation is complementary to, and often goes deeper -than, the doc-strings of each component in the [API](../Evennia-API.md). +These are the 'building blocks' out of which Evennia is built. This documentation is complementary to, and often goes deeper than, the doc-strings of each component in the [API](../Evennia-API.md). ## Database entites diff --git a/docs/source/Contribs/Contrib-Menu-Login.md b/docs/source/Contribs/Contrib-Menu-Login.md index 9c47216b6d..927210e3cf 100644 --- a/docs/source/Contribs/Contrib-Menu-Login.md +++ b/docs/source/Contribs/Contrib-Menu-Login.md @@ -11,7 +11,7 @@ menu system `EvMenu` under the hood. To install, add this to `mygame/server/conf/settings.py`: CMDSET_UNLOGGEDIN = "evennia.contrib.base_systems.menu_login.UnloggedinCmdSet" - CONNECTION_SCREEN_MODULE = "contrib.base_systems.menu_login.connection_screens" + CONNECTION_SCREEN_MODULE = "evennia.contrib.base_systems.menu_login.connection_screens" Reload the server and reconnect to see the changes. diff --git a/docs/source/Howtos/Howtos-Overview.md b/docs/source/Howtos/Howtos-Overview.md index d0cac98f1a..190387dd83 100644 --- a/docs/source/Howtos/Howtos-Overview.md +++ b/docs/source/Howtos/Howtos-Overview.md @@ -1,10 +1,6 @@ # Tutorials and Howto's -The documents in this section aims to teach how to use Evennia in a tutorial or -a step-by-step way. They often give hints on about solving a problem or implementing -a particular feature or concept. They will often refer to the -[components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md) -docs for those that want to dive deeper. +All Evennia tutorials. They will often refer to the [components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md) if you want to dive deeper. ## Beginner Tutorial diff --git a/docs/source/Setup/Installation-Git.md b/docs/source/Setup/Installation-Git.md index 1ffffa220a..00c3fc89de 100644 --- a/docs/source/Setup/Installation-Git.md +++ b/docs/source/Setup/Installation-Git.md @@ -1,7 +1,6 @@ # Installing with GIT -This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia -itself or have an easier time exploring the code. See the basic [Installation](./Installation.md) for +This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia itself or have an easier time exploring the code. See the basic [Installation](./Installation.md) for a quick installation of the library. See the [troubleshooting](./Installation-Troubleshooting.md) if you run into trouble. diff --git a/docs/source/Setup/Installation-Non-Interactive.md b/docs/source/Setup/Installation-Non-Interactive.md index 7095260830..3a056858d3 100644 --- a/docs/source/Setup/Installation-Non-Interactive.md +++ b/docs/source/Setup/Installation-Non-Interactive.md @@ -1,6 +1,6 @@ # Non-interactive setup -The first ime you run `evennia start` (just after having created the database), you will be asked +The first time you run `evennia start` (just after having created the database), you will be asked to interactively insert the superuser username, email and password. If you are deploying Evennia as part of an automatic build script, you don't want to enter this information manually. diff --git a/docs/source/Setup/Installation.md b/docs/source/Setup/Installation.md index 7dbb5449f7..6a6fa7232c 100644 --- a/docs/source/Setup/Installation.md +++ b/docs/source/Setup/Installation.md @@ -1,14 +1,5 @@ # Installation -The Evennia server is installed, run and maintained from the terminal (console/CMD on Windows). Starting the server -doesn't make anything visible online. Once you download everything you can in fact develop your game in complete -isolation if you want, without needing any access to the internet. - -Evennia requires [Python](https://www.python.org/downloads/) 3.9 or 3.10. -Using a [Python virtualenv](../Glossary.md#virtualenv) is highly recommended in order to keep your -Evennia installation independent from the system libraries. Don't install Evennia as -administrator or superuser. - ```{warning} pip install evennia is not yet available in develop branch. Use the [git installation](./Installation-Git.md). ``` @@ -16,13 +7,24 @@ pip install evennia is not yet available in develop branch. Use the [git install If you are converting an existing game from a previous version, [see here](./Installation-Upgrade.md). ``` + +- Evennia requires [Python](https://www.python.org/downloads/) 3.9 or 3.10. +- Using a [Python virtualenv](../Glossary.md#virtualenv) is highly recommended in order to keep your +Evennia installation independent from the system libraries. +- Don't install Evennia as +administrator or superuser. + +Evennia is managed from the terminal (console/CMD on Windows). If you have a suitable Python installed, you can install with + pip install evennia -Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a -virtualenv, make sure it's active whenever you need to use the `evennia` command. - Alternatively, you can [install Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). -Check out [installation troubleshooting](./Installation-Troubleshooting.md) if you run into problems. Some + +Installing doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection. + +Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it's active whenever you need to use the `evennia` command. + +> Check out [installation troubleshooting](./Installation-Troubleshooting.md) if you run into problems. Some users have also experimented with [installing Evennia on Android](./Installation-Android.md). ## Initialize a new game @@ -42,18 +44,15 @@ contains empty templates and all the default settings needed to start the server cd mygame evennia migrate -This will create the default database (Sqlite3). The database file ends up as `mygame/server/evennia.db3`. If you -ever want to start from a fresh database, just delete this file and re-run `evennia migrate` again. +This will create the default database (Sqlite3). The database file ends up as `mygame/server/evennia.db3`. If you ever want to start from a fresh database, just delete this file and re-run `evennia migrate` again. evennia start -Set your user-name and password when prompted. This will be the "god user" or "superuser" in-game. -The email is optional. +Set your user-name and password when prompted. This will be the "god user" or "superuser" in-game. The email is optional. > You can also [automate](./Installation-Non-Interactive.md) the creation of the super user. -If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or -a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game! +If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game! Log in as a new account or use the superuser you just created. @@ -93,8 +92,7 @@ To exit the log tailing, enter `Ctrl-C` (`Cmd-C` for Mac). This will not affect ## Server configuration -The server configuration file is `mygame/server/settings.py`. It's empty by default. Copy and change -only the settings you want from the [default settings file](./Settings-Default.md). +The server configuration file is `mygame/server/settings.py`. It's empty by default. Copy and change only the settings you want from the [default settings file](./Settings-Default.md). ## Register with the Evennia Game Index (optional) @@ -111,10 +109,4 @@ beforehand to make sure you don't pick a game name that is already taken - be ni You are good to go! -Evennia comes with a small [Tutorial World](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Tutorial-World.md) to experiment and learn from. After logging -in, you can create it by running - - batchcommand tutorial_world.build - -Next, why not head into the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) -to learn how to start making your new game! \ No newline at end of file +Next, why not head into the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) to learn how to start making your new game! \ No newline at end of file diff --git a/docs/source/Setup/Setup-Overview.md b/docs/source/Setup/Setup-Overview.md index eed92376a1..8adb04aee4 100644 --- a/docs/source/Setup/Setup-Overview.md +++ b/docs/source/Setup/Setup-Overview.md @@ -1,7 +1,6 @@ # Server Setup and Life -This documentation covers how to setup and maintain the server, -from first install to opening your game to the public. +This sums up all steps of maintaining your Evennia game from first installation to production release. ## Installation & running diff --git a/docs/source/Setup/Start-Stop-Reload.md b/docs/source/Setup/Start-Stop-Reload.md index 80cb76cf3e..e3a6880cb2 100644 --- a/docs/source/Setup/Start-Stop-Reload.md +++ b/docs/source/Setup/Start-Stop-Reload.md @@ -3,10 +3,11 @@ You control Evennia from your game folder (we refer to it as `mygame/` here), using the `evennia` program. If the `evennia` program is not available on the command line you must first install -Evennia as described in the [Setup Quickstart](./Installation.md) page. +Evennia as described on the [Installation](./Installation.md) page. -> Hint: If you ever try the `evennia` command and get an error complaining that the command is not -available, make sure your [virtualenv](../Glossary.md#virtualenv) is active. +```{sidebar} evennia not found? +If you ever try the `evennia` command and get an error complaining that the command is not available, make sure your [virtualenv](../Glossary.md#virtualenv) is active. +``` Below are described the various management options. Run @@ -20,7 +21,7 @@ to give you a menu with options. ## Starting Evennia -Evennia consists of two components, the Evennia [Server and Portal](../Components/Portal-And-Server.md). Briefly, +Evennia consists of two components, the Evennia [Portal and Server](../Components/Portal-And-Server.md). Briefly, the *Server* is what is running the mud. It handles all game-specific things but doesn't care exactly how players connect, only that they have. The *Portal* is a gateway to which players connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the @@ -28,10 +29,7 @@ game. Both are required for a functioning mud. evennia start -The above command will start the Portal, which in turn will boot up the Server. The command will -print a summary of the process and unless there is an error you will see no further output. Both -components will instead log to log files in `mygame/server/logs/`. For convenience you can follow -those logs directly in your terminal by attaching `-l` to commands: +The above command will start the Portal, which in turn will boot up the Server. The command will print a summary of the process and unless there is an error you will see no further output. Both components will instead log to log files in `mygame/server/logs/`. For convenience you can follow those logs directly in your terminal by attaching `-l` to commands: evennia -l @@ -41,23 +39,6 @@ Will start following the logs of an already running server. When starting Evenni > To stop viewing the log files, press `Ctrl-C`. -## Foreground mode - -Normally, Evennia runs as a 'daemon', in the background. If you want you can start either of the -processes (but not both) as foreground processes in *interactive* mode. This means they will log -directly to the terminal (rather than to log files that we then echo to the terminal) and you can -kill the process (not just the log-file view) with `Ctrl-C`. - - evennia istart - -will start/restart the *Server* in interactive mode. This is required if you want to run a -*debugger*. Next time you reload the server, it will return to normal mode. - - evennia ipstart - -will start the *Portal* in interactive mode. This is usually only necessary if you want to run -Evennia under the control of some other type of process. - ## Reloading The act of *reloading* means the Portal will tell the Server to shut down and then boot it back up @@ -78,6 +59,36 @@ From in-game the `@reload` command is used. You can also reload the server from Sometimes reloading from "the outside" is necessary in case you have added some sort of bug that blocks in-game input. +## Stopping + +A full shutdown closes Evennia completely, both Server and Portal. All accounts will be booted and +systems saved and turned off cleanly. + +From inside the game you initiate a shutdown with the `@shutdown` command. From command line you do + + evennia stop + +You will see messages of both Server and Portal closing down. All accounts will see the shutdown +message and then be disconnected. The same effect happens if you press `Ctrl+C` while the server +runs in interactive mode. + + +## Foreground mode + +Normally, Evennia runs as a 'daemon', in the background. If you want you can start either of the +processes (but not both) as foreground processes in *interactive* mode. This means they will log +directly to the terminal (rather than to log files that we then echo to the terminal) and you can +kill the process (not just the log-file view) with `Ctrl-C`. + + evennia istart + +will start/restart the *Server* in interactive mode. This is required if you want to run a +[debugger](Debugging). Next time you `evennia reload` the server, it will return to normal mode. + + evennia ipstart + +will start the *Portal* in interactive mode. + ## Resetting *Resetting* is the equivalent of a "cold reboot" - the Server will shut down and then restarted @@ -103,20 +114,6 @@ This is identical to doing these two commands: evennia stop evennia start - -## Shutting down - -A full shutdown closes Evennia completely, both Server and Portal. All accounts will be booted and -systems saved and turned off cleanly. - -From inside the game you initiate a shutdown with the `@shutdown` command. From command line you do - - evennia stop - -You will see messages of both Server and Portal closing down. All accounts will see the shutdown -message and then be disconnected. The same effect happens if you press `Ctrl+C` while the server -runs in interactive mode. - ## Status and info To check basic Evennia settings, such as which ports and services are active, this will repeat the @@ -134,7 +131,7 @@ This can be useful for automating checks to make sure the game is running and is ## Killing (Linux/Mac only) In the extreme case that neither of the server processes locks up and does not respond to commands, -you can send them kill-signals to force them to shut down. To kill only the Server: +[]()you can send them kill-signals to force them to shut down. To kill only the Server: evennia skill @@ -147,19 +144,17 @@ Note that this functionality is not supported on Windows. ## Django options -The `evennia` program will also pass-through options used by the `django-admin`. These operate on -the database in various ways. +The `evennia` program will also pass-through options used by the `django-admin`. These operate on the database in various ways. ```bash evennia migrate # migrate the database evennia shell # launch an interactive, django-aware python shell - evennia dbshell # launch database shell + evennia dbshell # launch the database shell ``` -For (many) more options, see [the django-admin -docs](https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage). +For (many) more options, see [the django-admin docs](https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage). ## Advanced handling of Evennia processes @@ -168,10 +163,7 @@ such as Linux' `top` or the more advanced `htop`), you will find the following p related to Evennia: * 1 x `twistd ... evennia/server/portal/portal.py` - this is the Portal process. -* 3 x `twistd ... server.py` - One of these processes manages Evennia's Server component, the main - game. The other processes (with the same name but different process id) handle's Evennia's - internal web server threads. You can look at `mygame/server/server.pid` to determine which is the - main process. +* 3 x `twistd ... server.py` - One of these processes manages Evennia's Server component, the main game. The other processes (with the same name but different process id) handle's Evennia's internal web server threads. You can look at `mygame/server/server.pid` to determine which is the main process. ### Syntax errors during live development @@ -193,4 +185,4 @@ Fix your bug then run evennia start Assuming the bug was fixed, this will start the Server manually (while not restarting the Portal). -In-game you should now get the message that the Server has successfully restarted. +In-game you should now get the message that the Server has successfully restarted. \ No newline at end of file diff --git a/docs/source/index.md b/docs/source/index.md index 11eba37116..d78e95874b 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -14,27 +14,35 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python `MU*` creation system. - [Evennia Introduction](./Evennia-Introduction.md) -- [Installation](Setup/Installation.md) -- [Beginner Tutorial](Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md) - [How to contribute and get help](./Contributing.md) -## Main sections +## Setup -- [Server Setup, Maintenance and Life](Setup/Setup-Overview.md) - how to run, maintain and release -- [Tutorials and Howto's](Howtos/Howtos-Overview.md) - projects and hints for reaching particular effects and goals ----- +- [Installation](Setup/Installation.md) +- [Starting, Stopping and Reloading](Setup/Start-Stop-Reload.md) - how to manage the Evennia server +- [Setup and configuration](Setup/Setup-Overview.md) - how to run, maintain and release + +## Howtos and Tutorials + +- [The Beginner Tutorial](Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md) - learn the basics and build a small game (in progress) +- [Tutorials and Howto's](Howtos/Howtos-Overview.md) - mixed tutorials to learn Evennia + +## Developing with Evennia - [Core components](Components/Components-Overview.md) - the core building blocks of Evennia - [Concepts](Concepts/Concepts-Overview.md) - larger-scale concepts and features ----- - - [API](./Evennia-API.md) - the full API-reference, generated from source - [Default Commands](Components/Default-Commands.md) - list of game commands included out of the box - [Coding](Coding/Coding-Overview.md) - coding and development hints and resources -- [Contribs](Contribs/Contribs-Overview.md) - game-specific tools and code added by the community ----- -- [Links](./Links.md) - useful links + +## Contributions and Info + +- [Contribs](Contribs/Contribs-Overview.md) - game-specific code and snippets to use for your game - [How to contribute to these docs](./Contributing-Docs.md) - if you want to help out +- [Links](./Links.md) - useful links +- [Licensing](./Licensing.md) - Evennia licensing info (BSD) + +---- ## All Sections