Updated HTML docs

This commit is contained in:
Griatch 2021-10-26 21:41:11 +02:00
parent 66d0ad0bc9
commit 7900aad365
2073 changed files with 32986 additions and 41197 deletions

View file

@ -5,18 +5,18 @@ need to adopt some best practices as well as find a good place to start to learn
Here are some pointers to get you going.
### Start with the tutorial
## Start with the tutorial
It's highly recommended that you jump in on the [Starting Tutorial](../Howto/Starting/Part1/Starting-Part1). Even if
It's highly recommended that you jump in on the [Starting Tutorial](../Howto/Starting/Part1/Starting-Part1.md). Even if
you only the beginning or some part of it, it covers much of the things needed to get started.
### Python
## Python
Evennia is developed using Python. Even if you are more of a designer than a coder, it is wise to
learn how to read and understand basic Python code. If you are new to Python, or need a refresher,
take a look at our [Python introduction](../Howto/Starting/Part1/Python-basic-introduction).
take a look at our [Python introduction](../Howto/Starting/Part1/Python-basic-introduction.md).
### Explore Evennia interactively
## Explore Evennia interactively
When new to Evennia it can be hard to find things or figure out what is available. Evennia offers a
special interactive python shell that allows you to experiment and try out things. It's recommended
@ -35,13 +35,13 @@ This will open an Evennia-aware python shell (using ipython). From within this s
evennia.<TAB>
That is, enter `evennia.` and press the `<TAB>` key. This will show you all the resources made
available at the top level of Evennia's "flat API". See the [flat API](../Evennia-API) page for more
available at the top level of Evennia's "flat API". See the [flat API](../Evennia-API.md) page for more
info on how to explore it efficiently.
#### Jupyter Notebook Support
### Jupyter Notebook Support
You can also explore evennia interactively in a [Jupyter notebook](https://jupyter.readthedocs.io/en/latest/index.html#). This offers
an in-browser view of your code similar to Matlab or similar programs. There are
an in-browser view of your code similar to Matlab or similar programs. There are
a few extra steps that must be taken in order for this to work:
# [open a new console/terminal]
@ -51,7 +51,7 @@ a few extra steps that must be taken in order for this to work:
Next, `cd` to your game folder. _It's important that you are in the _root_ of this folder for the next command_:
evennia shell_plus --notebook &
evennia shell_plus --notebook &
The `&` at the end starts the process as a background process on Linux/Unix.
Skip it if your OS doesn't support this syntax. Your browser should now open
@ -59,7 +59,7 @@ with the Jupyter interface. If not, open a browser to the link given on the
command line.
In the window, open the `new` menu in the top right and start a `Django Shell-Plus` notebook (or
open an existing one if you had one from before). In the first cell you must initialize
open an existing one if you had one from before). In the first cell you must initialize
Evennia like so:
```python
@ -71,13 +71,13 @@ _Note that the above initialization must be run every time a new new notebook/ke
After this you can import and access all of the Evennia system, same as with `evennia shell`.
#### More exploration
### More exploration
You can complement your exploration by peeking at the sections of the much more detailed
[Evennia Component overview](../Components/Components-Overview). The [Tutorials](../Howto/Howto-Overview) section also contains a growing collection
You can complement your exploration by peeking at the sections of the much more detailed
[Evennia Component overview](../Components/Components-Overview.md). The [Tutorials](../Howto/Howto-Overview.md) section also contains a growing collection
of system- or implementation-specific help.
### Use a python syntax checker
## Use a python syntax checker
Evennia works by importing your own modules and running them as part of the server. Whereas Evennia
should just gracefully tell you what errors it finds, it can nevertheless be a good idea for you to
@ -89,12 +89,12 @@ many python syntax checkers out there. A fast and easy one is
every possible problem - some bugs or problems will only appear when you actually run the code. But
using such a checker can be a good start to weed out the simple problems.
### Plan before you code
## Plan before you code
Before you start coding away at your dream game, take a look at our [Game Planning](../Howto/Starting/Part2/Game-Planning)
Before you start coding away at your dream game, take a look at our [Game Planning](../Howto/Starting/Part2/Game-Planning.md)
page. It might hopefully help you avoid some common pitfalls and time sinks.
### Code in your game folder, not in the evennia/ repository
## Code in your game folder, not in the evennia/ repository
As part of the Evennia setup you will create a game folder to host your game code. This is your
home. You should *never* need to modify anything in the `evennia` library (anything you download
@ -103,9 +103,9 @@ it out into your game folder and edit it there.
If you find that Evennia doesn't support some functionality you need, make a [Feature
Request](github:issue) about it. Same goes for [bugs][bug]. If you add features or fix bugs
yourself, please consider [Contributing](../Contributing) your changes upstream!
yourself, please consider [Contributing](../Contributing.md) your changes upstream!
### Learn to read tracebacks
## Learn to read tracebacks
Python is very good at reporting when and where things go wrong. A *traceback* shows everything you
need to know about crashing code. The text can be pretty long, but you usually are only interested
@ -124,7 +124,7 @@ module holding your custom class. Since such a module is not valid Python, Evenn
all. Instead of crashing, Evennia will then print the full traceback to the terminal/console and
temporarily fall back to the safe `DefaultObject` until you fix the problem and reload.
### Docs are here to help you
## Docs are here to help you
Some people find reading documentation extremely dull and shun it out of principle. That's your
call, but reading docs really *does* help you, promise! Evennia's documentation is pretty thorough
@ -133,7 +133,7 @@ can't find the answer in the docs, don't be shy to ask questions! The [discussio
group](https://sites.google.com/site/evenniaserver/discussions) and the [irc
chat](https://webchat.freenode.net/?channels=evennia) are also there for you.
### The most important point
## The most important point
And finally, of course, have fun!

View file

@ -7,24 +7,24 @@ to you, but some things may still be useful.
## Find your way
- [Directory-Overview](../Howto/Starting/Part1/Gamedir-Overview)
- [Quirks of Evennia](./Quirks)
- [Directory-Overview](../Howto/Starting/Part1/Gamedir-Overview.md)
- [Quirks of Evennia](./Quirks.md)
## Setting up a workflow
- [Setting up PyCharm](./Setting-up-PyCharm)
- [Using Version-Control](./Version-Control)
- [Updating Evennia sources](./Updating-Your-Game)
- [Setting up PyCharm](./Setting-up-PyCharm.md)
- [Using Version-Control](./Version-Control.md)
- [Updating Evennia sources](./Updating-Your-Game.md)
## Coding away
- [Coding Introduction](./Coding-Introduction)
- [Ways to Debug](./Debugging)
- [Adding unit-tests](./Unit-Testing)
- [Things to remember when importing from evennia](./Flat-API)
- [Coding Introduction](./Coding-Introduction.md)
- [Ways to Debug](./Debugging.md)
- [Adding unit-tests](./Unit-Testing.md)
- [Things to remember when importing from evennia](./Flat-API.md)
## Advanced concepts
- [Continuous Integration](./Continuous-Integration)
- [Using Travis](./Using-Travis)
- [Profiling](./Profiling)
- [Continuous Integration](./Continuous-Integration.md)
- [Using Travis](./Using-Travis.md)
- [Profiling](./Profiling.md)

View file

@ -27,7 +27,7 @@ Among those you will need:
* A Continuous Integration Environment.
* I recommend [TeamCity](https://www.jetbrains.com/teamcity/) which has an in-depth [Setup
Guide](https://confluence.jetbrains.com/display/TCD8/Installing+and+Configuring+the+TeamCity+Server)
* [Source Control](./Version-Control)
* [Source Control](./Version-Control.md)
* This could be Git or SVN or any other available SC.
## Linux TeamCity Setup

View file

@ -1,7 +1,7 @@
# Things to remember about the flat API
The flat API is a series of 'shortcuts' on the `evennia` main library root (defined in
`evennia/__init__.py`). Its componentas are documented [as part of the auto-documentation](../Evennia-API).
`evennia/__init__.py`). Its componentas are documented [as part of the auto-documentation](../Evennia-API.md).
## To remember when importing from `evennia`

View file

@ -58,7 +58,7 @@ through the launcher:
This will start Evennia with the Server component running (in daemon mode) under
cProfile. You could instead try `--profile` with the `portal` argument to
profile the Portal (you would then need to
[start the Server separately](../Setup/Start-Stop-Reload)).
[start the Server separately](../Setup/Start-Stop-Reload.md)).
Please note that while the profiler is running, your process will use a lot more
memory than usual. Memory usage is even likely to climb over time. So don't
@ -127,7 +127,7 @@ game with simulated players (aka "bots" or "dummies"). Once connected, these
dummies will semi-randomly perform various tasks from a list of possible
actions. Use `Ctrl-C` to stop the Dummyrunner.
```warning::
```{warning}
You should not run the Dummyrunner on a production database. It
will spawn many objects and also needs to run with general permissions.

View file

@ -4,7 +4,7 @@
This is a list of various quirks or common stumbling blocks that people often ask about or report
when using (or trying to use) Evennia. They are not bugs.
### Forgetting to use @reload to see changes to your typeclasses
## Forgetting to use @reload to see changes to your typeclasses
Firstly: Reloading the server is a safe and usually quick operation which will *not* disconnect any
accounts.
@ -13,7 +13,7 @@ New users tend to forget this step. When editing source code (such as when tweak
commands or adding new commands to command sets) you need to either use the in-game `@reload`
command or, from the command line do `python evennia.py reload` before you see your changes.
### Web admin to create new Account
## Web admin to create new Account
If you use the default login system and are trying to use the Web admin to create a new Player
account, you need to consider which `MULTIACCOUNT_MODE` you are in. If you are in
@ -28,12 +28,12 @@ the "account" property on the Character and the "character" property on the Acco
other. You must also set the lockstring of the Character to allow the Account to "puppet" this
particular character.
### Mutable attributes and their connection to the database
## Mutable attributes and their connection to the database
When storing a mutable object (usually a list or a dictionary) in an Attribute
```python
object.db.mylist = [1,2,3]
object.db.mylist = [1,2,3]
```
you should know that the connection to the database is retained also if you later extract that
@ -62,16 +62,16 @@ use of `evennia.utils.dbserialize.deserialize`:
The property `blist` is now `[1,2,3,4]` whereas `object.db.mylist` remains unchanged. If you want to
update the database you'd need to explicitly re-assign the updated data to the `mylist` Attribute.
### Commands are matched by name *or* alias
## Commands are matched by name *or* alias
When merging [command sets](../Components/Commands) it's important to remember that command objects are identified
When merging [command sets](../Components/Commands.md) it's important to remember that command objects are identified
*both* by key *or* alias. So if you have a command with a key `look` and an alias `ls`, introducing
another command with a key `ls` will be assumed by the system to be *identical* to the first one.
This usually means merging cmdsets will overload one of them depending on priority. Whereas this is
logical once you know how command objects are handled, it may be confusing if you are just looking
at the command strings thinking they are parsed as-is.
### Objects turning to `DefaultObject`
## Objects turning to `DefaultObject`
A common confusing error for new developers is finding that one or more objects in-game are suddenly
of the type `DefaultObject` rather than the typeclass you wanted it to be. This happens when you
@ -82,7 +82,7 @@ back to the safe `DefaultObject` until you fix the problem and reload. Most erro
be caught by any good text editors. Keep an eye on the terminal/console during a reload to catch
such errors - you may have to scroll up if your window is small.
### Overriding of magic methods
## Overriding of magic methods
Python implements a system of [magic
methods](https://docs.python.org/3/reference/datamodel.html#emulating-container-types), usually
@ -104,17 +104,17 @@ can result in very inconsistent and hard-to-diagnose errors.
The moral of the story-- it can be dangerous to tinker with magic methods on typeclassed objects.
Try to avoid doing so.
### Known upstream bugs
## Known upstream bugs
- There is currently (Autumn 2017) a bug in the `zope.interface` installer on some Linux Ubuntu
distributions (notably Ubuntu 16.04 LTS). Zope is a dependency of Twisted. The error manifests in
the server not starting with an error that `zope.interface` is not found even though `pip list`
shows it's installed. The reason is a missing empty `__init__.py` file at the root of the zope
package. If the virtualenv is named "evenv" as suggested in the [Setup Quickstart](../Setup/Setup-Quickstart)
package. If the virtualenv is named "evenv" as suggested in the [Setup Quickstart](../Setup/Setup-Quickstart.md)
instructions, use the following command to fix it:
```shell
touch evenv/local/lib/python2.7/site-packages/zope/__init__.py
```
This will create the missing file and things should henceforth work correctly.
This will create the missing file and things should henceforth work correctly.

View file

@ -74,28 +74,28 @@ To test the results, you use special methods of the `TestCase` class. Many of t
"`assert`", such as `assertEqual` or `assertTrue`.
Example of a `TestCase` class:
```python
import unittest
# the function we want to test
from mypath import myfunc
class TestObj(unittest.TestCase):
"This tests a function myfunc."
def test_return_value(self):
"test method. Makes sure return value is as expected."
"test method. Makes sure return value is as expected."
expected_return = "This is me being nice."
actual_return = myfunc()
# test
# test
self.assertEqual(expected_return, actual_return)
def test_alternative_call(self):
"test method. Calls with a keyword argument."
expected_return = "This is me being baaaad."
actual_return = myfunc(bad=True)
# test
self.assertEqual(expected_return, actual_return)
self.assertEqual(expected_return, actual_return)
```
You might also want to read the [documentation for the unittest
@ -145,7 +145,7 @@ class in the same module to get access to the command-specific utilities mention
self.call(general.CmdLook(), "Char2", "Char2(#7)")
"tests the look command by simple call, with target as room"
def test_mycmd_room(self):
self.call(general.CmdLook(), "Room",
self.call(general.CmdLook(), "Room",
"Room(#1)\nroom_desc\nExits: out(#3)\n"
"You see: Obj(#4), Obj2(#5), Char2(#7)")
```
@ -153,7 +153,7 @@ class in the same module to get access to the command-specific utilities mention
### Unit testing contribs with custom models
A special case is if you were to create a contribution to go to the `evennia/contrib` folder that
uses its [own database models](../Concepts/New-Models). The problem with this is that Evennia (and Django) will
uses its [own database models](../Concepts/New-Models.md). The problem with this is that Evennia (and Django) will
only recognize models in `settings.INSTALLED_APPS`. If a user wants to use your contrib, they will
be required to add your models to their settings file. But since contribs are optional you cannot
add the model to Evennia's central `settings_default.py` file - this would always create your
@ -199,7 +199,7 @@ class TestMyModel(EvenniaTest):
from django.db.models import loading
loading.cache.loaded = False
call_command('syncdb', verbosity=0)
def tearDown(self):
settings.configure(**OLD_DEFAULT_SETTINGS)
django.setup()
@ -290,11 +290,11 @@ just to show how unit testing works:
# mygame/commands/tests.py
import unittest
class TestString(unittest.TestCase):
"""Unittest for strings (just a basic example)."""
def test_upper(self):
"""Test the upper() str method."""
self.assertEqual('foo'.upper(), 'FOO')
@ -317,7 +317,7 @@ Let's execute that test to see if it works.
.
----------------------------------------------------------------------
Ran 1 test in 0.001s
OK
Destroying test database for alias 'default'...
@ -330,7 +330,7 @@ to see how it looks when it fails.
### Testing commands
```warning:: This is not correct anymore.
```{warning} This is not correct anymore.
```
This section will test the proper execution of the 'abilities' command, as described in the DELETED
@ -349,14 +349,14 @@ already have in `commands` from before.
# bottom of mygame/commands/tests.py
from evennia.commands.default.tests import CommandTest
from commands.command import CmdAbilities
from typeclasses.characters import Character
class TestAbilities(CommandTest):
character_typeclass = Character
def test_simple(self):
self.call(CmdAbilities(), "", "STR: 5, AGI: 4, MAG: 2")
```
@ -392,7 +392,7 @@ Let's run our new test:
..
----------------------------------------------------------------------
Ran 2 tests in 0.156s
OK
Destroying test database for alias 'default'...

View file

@ -2,9 +2,9 @@
Fortunately, it's extremely easy to keep your Evennia server up-to-date. If you haven't already, see
the [Getting Started guide](../Setup/Setup-Quickstart) and get everything running.
the [Getting Started guide](../Setup/Setup-Quickstart.md) and get everything running.
### Updating with the latest Evennia code changes
## Updating with the latest Evennia code changes
Very commonly we make changes to the Evennia code to improve things. There are many ways to get told
when to update: You can subscribe to the RSS feed or manually check up on the feeds from
@ -30,7 +30,7 @@ the new code affect your game. If you want to be really sure you should run a fu
so that both Server and Portal can restart (this will disconnect everyone though, so if you know the
Portal has had no updates you don't have to do that).
### Upgrading Evennia dependencies
## Upgrading Evennia dependencies
On occasion we update the versions of third-party libraries Evennia depend on (or we may add a new
dependency). This will be announced on the mailing list/forum. If you run into errors when starting
@ -40,8 +40,8 @@ version that should not be used in production.
Upgrading `evennia` will automatically fetch all the latest packages that it now need. First `cd` to
your cloned `evennia` folder. Make sure your `virtualenv` is active and use
pip install --upgrade -e .
pip install --upgrade -e .
Remember the period (`.`) at the end - that applies the upgrade to the current location (your
`evennia` dir).
@ -55,7 +55,7 @@ source-code changes.
Follow the upgrade output to make sure it finishes without errors. To check what packages are
currently available in your python environment after the upgrade, use
pip list
pip list
This will show you the version of all installed packages. The `evennia` package will also show the
location of its source code.
@ -72,13 +72,13 @@ When the database schema changes, you just go to your game folder and run
evennia migrate
> Hint: If the `evennia` command is not found, you most likely need to activate your
[virtualenv](../Glossary#virtualenv).
[virtualenv](../Glossary.md#virtualenv).
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia
or anything like that. You just need to clear your database. Once you are done, you just rebuild it
from scratch by running
from scratch by running
evennia migrate
@ -131,4 +131,4 @@ automatically for you. Basically, whenever the schema changes we distribute smal
"migrations" with the source. Those tell the system exactly how to implement the change so you don't
have to do so manually. When a migration has been added we will tell you so on Evennia's mailing
lists and in commit messages -
you then just run `evennia migrate` to be up-to-date again.
you then just run `evennia migrate` to be up-to-date again.

View file

@ -324,7 +324,7 @@ developer mailing list or IRC chat to see beforehand if your feature is deemed s
as a core feature in the engine. When it comes to bug-fixes, other developers may also have good
input on how to go about resolving the issue.
To contribute you need to have [forked Evennia](./Version-Control#forking-evennia) first. As described
To contribute you need to have [forked Evennia](./Version-Control.md#forking-evennia) first. As described
above you should do your modification in a separate local branch (not in the master branch). This
branch is what you then present to us (as a *Pull request*, PR, see below). We can then merge your
change into the upstream master and you then do `git pull` to update master usual. Now that the