Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fixed all errors in doc building

Browse source
This commit is contained in:
Griatch 2020-07-11 00:14:13 +02:00
parent 9fbfc8f8d0
commit 76761825d0
80 changed files with 766 additions and 767 deletions
Download patch file Download diff file Expand all files Collapse all files

150
docs/source/Glossary.md
View file

@ -3,50 +3,50 @@
This explains common recurring terms used in the Evennia docs. It will be expanded as needed.
- _[account](Glossary#account)_ - the player's account on the game
- _[admin-site](Glossary#admin-site)_ - the Django web page for manipulating the database
- _[attribute](Glossary#attribute)_ - persistent, custom data stored on typeclasses
- _[channel](Glossary#channel)_ - game communication channels
- _[character](Glossary#character)_ - the player's avatar in the game, controlled from
_[account](Glossary#account)_
- _[core](Glossary#core)_ - a term used for the code distributed with Evennia proper
- _[django](Glossary#django)_ - web framework Evennia uses for database access and web integration
- _[field](Glossary#field)_ - a _[typeclass](Glossary#typeclass)_ property representing a database
- _[account](./Glossary#account)_ - the player's account on the game
- _[admin-site](./Glossary#admin-site)_ - the Django web page for manipulating the database
- _[attribute](./Glossary#attribute)_ - persistent, custom data stored on typeclasses
- _[channel](./Glossary#channel)_ - game communication channels
- _[character](./Glossary#character)_ - the player's avatar in the game, controlled from
_[account](./Glossary#account)_
- _[core](./Glossary#core)_ - a term used for the code distributed with Evennia proper
- _[django](./Glossary#django)_ - web framework Evennia uses for database access and web integration
- _[field](./Glossary#field)_ - a _[typeclass](./Glossary#typeclass)_ property representing a database
column
- _[git](Glossary#git)_ - the version-control system we use
- _[github](Glossary#github)_ - the online hosting of our source code
- _[migrate](Glossary#migrate)_ - updating the database schema
- _[git](./Glossary#git)_ - the version-control system we use
- _[github](./Glossary#github)_ - the online hosting of our source code
- _[migrate](./Glossary#migrate)_ - updating the database schema
- _[multisession mode`](#multisession-mode)_ - a setting defining how users connect to Evennia
- _[object](Glossary#object)_ - Python instance, general term or in-game
_[typeclass](Glossary#typeclass)_
- _[pip](Glossary#pip)_ - the Python installer
- _[object](./Glossary#object)_ - Python instance, general term or in-game
_[typeclass](./Glossary#typeclass)_
- _[pip](./Glossary#pip)_ - the Python installer
- _player_ - the human connecting to the game with their client
- _[puppet](Glossary#puppet)_ - when an [account](Glossary#account) controls an in-game
[object](Glossary#object)
- _[property](Glossary#property)_ - a python property
- _evenv_ - see _[virtualenv](Glossary#virtualenv)_
- _[repository](Glossary#repository)_ - a store of source code + source history
- _[script](Glossary#script)_ - a building block for custom storage, systems and time-keepint
- _[session](Glossary#session)_ - represents one client connection
- _[ticker](Glossary#ticker)_ - Allows to run events on a steady 'tick'
- _[twisted](Glossary#twisted)_ - networking engine responsible for Evennia's event loop and
- _[puppet](./Glossary#puppet)_ - when an [account](./Glossary#account) controls an in-game
[object](./Glossary#object)
- _[property](./Glossary#property)_ - a python property
- _evenv_ - see _[virtualenv](./Glossary#virtualenv)_
- _[repository](./Glossary#repository)_ - a store of source code + source history
- _[script](./Glossary#script)_ - a building block for custom storage, systems and time-keepint
- _[session](./Glossary#session)_ - represents one client connection
- _[ticker](./Glossary#ticker)_ - Allows to run events on a steady 'tick'
- _[twisted](./Glossary#twisted)_ - networking engine responsible for Evennia's event loop and
communications
- _[typeclass](Glossary#typeclass)_ - Evennia's database-connected Python class
- _upstream_ - see _[github](Glossary#github)_
- _[virtualenv](Glossary#virtualenv)_ - a Python program and way to make an isolated Python install
- _[typeclass](./Glossary#typeclass)_ - Evennia's database-connected Python class
- _upstream_ - see _[github](./Glossary#github)_
- _[virtualenv](./Glossary#virtualenv)_ - a Python program and way to make an isolated Python install
---
### _account_
The term 'account' refers to the [player's](Glossary#player) unique account on the game. It is
represented by the `Account` [typeclass](Glossary#typeclass) and holds things like email, password,
The term 'account' refers to the [player's](./Glossary#player) unique account on the game. It is
represented by the `Account` [typeclass](./Glossary#typeclass) and holds things like email, password,
configuration etc.
When a player connects to the game, they connect to their account. The account has *no*
representation in the game world. Through their Account they can instead choose to
[puppet](Glossary#puppet) one (or more, depending on game mode) [Characters](Glossary#character) in
[puppet](./Glossary#puppet) one (or more, depending on game mode) [Characters](./Glossary#character) in
the game.
In the default [multisession mode](Component/Sessions#multisession-mode) of Evennia, you immediately start
@ -55,16 +55,16 @@ servers used to work.
### _admin-site_
This usually refers to [Django's](Glossary#django) *Admin site* or database-administration web page
This usually refers to [Django's](./Glossary#django) *Admin site* or database-administration web page
([link to Django docs](https://docs.djangoproject.com/en/2.1/ref/contrib/admin/)). The admin site is
an automatically generated web interface to the database (it can be customized extensively). It's
reachable from the `admin` link on the default Evennia website you get with your server.
### _attribute_
The term _Attribute_ should not be confused with ([properties](Glossary#property) or
[fields](Glossary#field). The `Attribute` represents arbitrary pieces of data that can be attached
to any [typeclassed](Glossary#typeclass) entity in Evennia. Attributes allows storing new persistent
The term _Attribute_ should not be confused with ([properties](./Glossary#property) or
[fields](./Glossary#field). The `Attribute` represents arbitrary pieces of data that can be attached
to any [typeclassed](./Glossary#typeclass) entity in Evennia. Attributes allows storing new persistent
data on typeclasses without changing their underlying database schemas.
[Read more about Attributes here](Component/Attributes).
@ -72,23 +72,23 @@ data on typeclasses without changing their underlying database schemas.
A _Channel_ refers to an in-game communication channel. It's an entity that people subscribe to and
which re-distributes messages between all subscribers. Such subscribers default to being
[Accounts](Glossary#account), for out-of-game communication but could also be [Objects (usually
[Accounts](./Glossary#account), for out-of-game communication but could also be [Objects (usually
Characters)](Glossary#character) if one wanted to adopt Channels for things like in-game walkie-
talkies or phone systems. It is represented by the `Channel` typeclass. [You can read more about the
comm system here](Communications#channels).
### _character_
The _Character_ is the term we use for the default avatar being [puppeted](Glossary#puppet) by the
[account](Glossary#account) in the game world. It is represented by the `Character` typeclass (which
is a child of [Object](Glossary#object)). Many developers use children of this class to represent
The _Character_ is the term we use for the default avatar being [puppeted](./Glossary#puppet) by the
[account](./Glossary#account) in the game world. It is represented by the `Character` typeclass (which
is a child of [Object](./Glossary#object)). Many developers use children of this class to represent
monsters and other NPCs. You can [read more about it here](Component/Objects#subclasses-of-object).
### _django_
[Django](https://www.djangoproject.com/) is a professional and very popular Python web framework,
similar to Rails for the Ruby language. It is one of Evennia's central library dependencies (the
other one is [Twisted](Glossary#twisted)). Evennia uses Django for two main things - to map all
other one is [Twisted](./Glossary#twisted)). Evennia uses Django for two main things - to map all
database operations to Python and for structuring our web site.
Through Django, we can work with any supported database (SQlite3, Postgres, MySQL ...) using generic
@ -97,7 +97,7 @@ Python instead of database-specific SQL: A database table is represented in Djan
There is usually no need to know the details of Django's database handling in order to use Evennia -
it will handle most of the complexity for you under the hood using what we call
[typeclasses](Glossary#typeclass). But should you need the power of Django you can always get it.
[typeclasses](./Glossary#typeclass). But should you need the power of Django you can always get it.
Most commonly people want to use "raw" Django when doing more advanced/custom database queries than
offered by Evennia's [default search functions](Howto/Starting/Part1/Searching-Things). One will then need
to read about Django's _querysets_. Querysets are Python method calls on a special form that lets
@ -115,24 +115,24 @@ when a user goes that URL in their browser, enters data into a form etc. The ret
to show. Django also offers templating with features such as being able to add special markers in
HTML where it will insert the values of Python variables on the fly (like showing the current player
count on the web page). [Here is one of our tutorials on wiring up such a web page](Add-a-simple-
new-web-page). Django also comes with the [admin site](Glossary#admin-site), which automatically
new-web-page). Django also comes with the [admin site](./Glossary#admin-site), which automatically
maps the database into a form accessible from a web browser.
### _core_
This term is sometimes used to represent the main Evennia library code suite, *excluding* its
[contrib](Glossary#contrib) directory. It can sometimes come up in code reviews, such as
[contrib](./Glossary#contrib) directory. It can sometimes come up in code reviews, such as
> Evennia is game-agnostic but this feature is for a particular game genre. So it does not belong in
core. Better make it a contrib.
### _field_
A _field_ or _database field_ in Evennia refers to a [property](Glossary#property) on a
[typeclass](Glossary#typeclass) directly linked to an underlying database column. Only a few fixed
A _field_ or _database field_ in Evennia refers to a [property](./Glossary#property) on a
[typeclass](./Glossary#typeclass) directly linked to an underlying database column. Only a few fixed
properties per typeclass are database fields but they are often tied to the core functionality of
that base typeclass (for example [Objects](Glossary#object) store its location as a field). In all
other cases, [attributes](Glossary#attribute) are used to add new persistent data to the typeclass.
that base typeclass (for example [Objects](./Glossary#object) store its location as a field). In all
other cases, [attributes](./Glossary#attribute) are used to add new persistent data to the typeclass.
[Read more about typeclass properties here](Component/Typeclasses#about-typeclass-properties).
### _git_
@ -143,12 +143,12 @@ tool. It allows us to track the development of the Evennia code by dividing it i
come back to it later if later changes caused problems. By tracking commits we know what 'version'
of the code we are currently using.
Evennia's source code + its source history is jointly called a [repository](Glossary#repository).
This is centrally stored at our online home on [GitHub](Glossary#github). Everyone using or
Evennia's source code + its source history is jointly called a [repository](./Glossary#repository).
This is centrally stored at our online home on [GitHub](./Glossary#github). Everyone using or
developing Evennia makes a 'clone' of this repository to their own computer - everyone
automatically gets everything that is online, including all the code history.
> Don't confuse Git and [GitHub](Glossary#github). The former is the version control system. The
> Don't confuse Git and [GitHub](./Glossary#github). The former is the version control system. The
latter is a website (run by a company) that allows you to upload source code controlled by Git for
others to see (among other things).
@ -172,13 +172,13 @@ you 'download' Evennia. You only need to do this once.
### _migrate_
This term is used for upgrading the database structure (it's _schema_ )to a new version. Most often
this is due to Evennia's [upstream](Glossary#github) schema changing. When that happens you need to
migrate that schema to the new version as well. Once you have used [git](Glossary#git) to pull the
this is due to Evennia's [upstream](./Glossary#github) schema changing. When that happens you need to
migrate that schema to the new version as well. Once you have used [git](./Glossary#git) to pull the
latest changes, just `cd` into your game dir and run
evennia migrate
That should be it (see [virtualenv](Glossary#virtualenv) if you get a warning that the `evennia`
That should be it (see [virtualenv](./Glossary#virtualenv) if you get a warning that the `evennia`
command is not available). See also [Updating your game](Coding/Updating-Your-Game) for more details.
> Technically, migrations are shipped as little Python snippets of code that explains which database
@ -195,23 +195,23 @@ here](Sessions#multisession-mode).
### _github_
[Github](https://github.com/evennia) is where Evennia's source code and documentation is hosted.
This online [repository](Glossary#repository) of code we also sometimes refer to as _upstream_.
This online [repository](./Glossary#repository) of code we also sometimes refer to as _upstream_.
GitHub is a business, offering free hosting to Open-source projects like Evennia. Despite the
similarity in name, don't confuse GitHub the website with [Git](Glossary#git), the versioning
system. Github hosts Git [repositories](Glossary#repository) online and helps with collaboration and
similarity in name, don't confuse GitHub the website with [Git](./Glossary#git), the versioning
system. Github hosts Git [repositories](./Glossary#repository) online and helps with collaboration and
infrastructure. Git itself is a separate project.
### _object_
In general Python (and other [object-oriented languages](https://en.wikipedia.org/wiki/Object-
oriented_programming)), an `object` is what we call the instance of a *class*. But one of Evennia's
core [typeclasses](Glossary#typeclasss) is also called "Object". To separate these in the docs we
core [typeclasses](./Glossary#typeclasss) is also called "Object". To separate these in the docs we
try to use `object` to refer to the general term and capitalized `Object` when we refer to the
typeclass.
The `Object` is a typeclass that represents all *in-game* entities, including
[Characters](Glossary#character), rooms, trees, weapons etc. [Read more about Objects here](Component/Objects).
[Characters](./Glossary#character), rooms, trees, weapons etc. [Read more about Objects here](Component/Objects).
### _pip_
@ -232,14 +232,14 @@ means that if the code in `<folder>` changes, the installed Python package is im
If not using `-e`, one would need to run `pip install --upgrade <folder>` every time to make the
changes available when you import this package into your code. Evennia is installed this way.
For development, `pip` is usually used together with a [virtualenv](Glossary#virtualenv) to install
For development, `pip` is usually used together with a [virtualenv](./Glossary#virtualenv) to install
all packages and dependencies needed for a project in one, isolated location on the hard drive.
### _puppet_
An [account](Glossary#account) can take control and "play as" any [Object](Glossary#object). When
An [account](./Glossary#account) can take control and "play as" any [Object](./Glossary#object). When
doing so, we call this _puppeting_, (like [puppeteering](https://en.wikipedia.org/wiki/Puppeteer)).
Normally the entity being puppeted is of the [Character](Glossary#character) subclass but it does
Normally the entity being puppeted is of the [Character](./Glossary#character) subclass but it does
not have to be.
### _property_
@ -247,25 +247,25 @@ not have to be.
A _property_ is a general term used for properties on any Python object. The term also sometimes
refers to the `property` built-in function of Python ([read more here](https://www.python-
course.eu/python3_properties.php)). Note the distinction between properties,
[fields](Glossary#field) and [Attributes](Glossary#attribute).
[fields](./Glossary#field) and [Attributes](./Glossary#attribute).
### _repository_
A _repository_ is a version control/[git](Glossary#git) term. It represents a folder containing
A _repository_ is a version control/[git](./Glossary#git) term. It represents a folder containing
source code plus its versioning history.
> In Git's case, that history is stored in a hidden folder `.git`. If you ever feel the need to look
into this folder you probably already know enough Git to know why.
The `evennia` folder you download from us with `git clone` is a repository. The code on
[GitHub](Glossary#github) is often referred to as the 'online repository' (or the _upstream_
[GitHub](./Glossary#github) is often referred to as the 'online repository' (or the _upstream_
repository). If you put your game dir under version control, that of course becomes a repository as
well.
### _script_
When we refer to _Scripts_, we generally refer to the `Script` [typeclass](Component/Typeclasses). Scripts are
the mavericks of Evennia - they are like [Objects](Glossary#object) but without any in-game
the mavericks of Evennia - they are like [Objects](./Glossary#object) but without any in-game
existence. They are useful as custom places to store data but also as building blocks in persistent
game systems. Since the can be initialized with timing capabilities they can also be used for long-
time persistent time keeping (for fast updates other types of timers may be better though).
@ -276,9 +276,9 @@ time persistent time keeping (for fast updates other types of timers may be bett
A [Session](Component/Sessions) is a Python object representing a single client connection to the server. A
given human player could connect to the game from different clients and each would get a Session
(even if you did not allow them to actually log in and get access to an
[account](Glossary#account)).
[account](./Glossary#account)).
Sessions are _not_ [typeclassed](Glossary#typeclass) and has no database persistence. But since they
Sessions are _not_ [typeclassed](./Glossary#typeclass) and has no database persistence. But since they
always exist (also when not logged in), they share some common functionality with typeclasses that
can be useful for certain game states.
@ -295,25 +295,25 @@ to be called when those ticks come around.
The [typeclass](Component/Typeclasses) is an Evennia-specific term. A typeclass allows developers to work with
database-persistent objects as if they were normal Python objects. It makes use of specific
[Django](Glossary#django) features to link a Python class to a database table. Sometimes we refer to
[Django](./Glossary#django) features to link a Python class to a database table. Sometimes we refer to
such code entities as _being typeclassed_.
Evennia's main typeclasses are [Account](Glossary#account), [Object](Glossary#object),
[Script](Glossary#script) and [Channel](Glossary#channel). Children of the base class (such as
[Character](Glossary#character)) will use the same database table as the parent, but can have vastly
different Python capabilities (and persistent features through [Attributes](Glossary#attributes) and
[Tags](Glossary#tags). A typeclass can be coded and treated pretty much like any other Python class
Evennia's main typeclasses are [Account](./Glossary#account), [Object](./Glossary#object),
[Script](./Glossary#script) and [Channel](./Glossary#channel). Children of the base class (such as
[Character](./Glossary#character)) will use the same database table as the parent, but can have vastly
different Python capabilities (and persistent features through [Attributes](./Glossary#attributes) and
[Tags](./Glossary#tags). A typeclass can be coded and treated pretty much like any other Python class
except it must inherit (at any distance) from one of the base typeclasses. Also, creating a new
instance of a typeclass will add a new row to the database table to which it is linked.
The [core](Glossary#core) typeclasses in the Evennia library are all named `DefaultAccount`,
The [core](./Glossary#core) typeclasses in the Evennia library are all named `DefaultAccount`,
`DefaultObject` etc. When you initialize your [game dir] you automatically get empty children of
these, called `Account`, `Object` etc that you can start working with.
### _twisted_
[Twisted](https://twistedmatrix.com/trac/) is a heavy-duty asynchronous networking engine. It is one
of Evennia's two major library dependencies (the other one is [Django](Glossary#django)). Twisted is
of Evennia's two major library dependencies (the other one is [Django](./Glossary#django)). Twisted is
what "runs" Evennia - it handles Evennia's event loop. Twisted also has the building blocks we need
to construct network protocols and communicate with the outside world; such as our MUD-custom
version of Telnet, Telnet+SSL, SSH, webclient-websockets etc. Twisted also runs our integrated web
@ -339,7 +339,7 @@ Python version than default.
A virtualenv is 'activated' only for the console/terminal it was started in, but it's safe to
activate the same virtualenv many times in different windows if you want. Once activated, all Python
packages now installed with [pip](Glossary#pip) will install to `evenv` rather than to a global
packages now installed with [pip](./Glossary#pip) will install to `evenv` rather than to a global
location like `/usr/local/bin` or `C:\Program Files`.
> Note that if you have root/admin access you *could* install Evennia globally just fine, without