Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-27 18:26:32 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update and clean up docs

Browse source
This commit is contained in:
Griatch 2022-11-20 01:36:35 +01:00
parent ea8eedc3bf
commit d1ddb80b22
9 changed files with 380 additions and 478 deletions
Download patch file Download diff file Expand all files Collapse all files

72
docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Evennia-Library-Overview.md
View file

@ -4,18 +4,11 @@
API stands for `Application Programming Interface`, a description for how to access the resources of a program or library.
```
A good place to start exploring Evennia is the [Evenia-API frontpage](../../../Evennia-API.md).
This page sums up the main components of Evennia with a short description of each. Try clicking through
to a few entries - once you get deep enough you'll see full descriptions
of each component along with their documentation. You can also click `[source]` to see the full Python source
for each thing.
You can also browse [the evennia repository on github](https://github.com/evennia/evennia). This is exactly
what you can download from us. The github repo is also searchable.
Finally, you can clone the evennia repo to your own computer and read the sources locally. This is necessary
if you want to help with Evennia's development itself. See the
[extended install instructions](../../../Setup/Installation-Git.md) if you want to do this.
There are several good ways to explore the Evennia library.
- This documentation contains the [Evennia-API docs](../../../Evennia-API.md), generated automatically from sources. Try clicking through to a few entries - once you get deep enough you'll see full descriptions of each component along with their documentation. You can also click `[source]` to see the full Python source code for each thing.
- There are [separate doc pages for each component](../../../Components/Components-Overview.md) if you want more detailed explanations.
- You can browse [the evennia repository on github](https://github.com/evennia/evennia). This is exactly what you can download from us.
- Finally, you can clone the evennia repo to your own computer and read the sources. This is necessary if you want to *really* understand what's going on, or help with Evennia's development. See the [extended install instructions](../../../Setup/Installation-Git.md) if you want to do this.
## Where is it?
@ -27,10 +20,9 @@ If Evennia is installed, you can import from it simply with
and so on.
If you installed Evennia with `pip install`, the library folder will be installed deep inside your Python
installation. If you cloned the repo there will be a folder `evennia` on your hard drive there.
If you installed Evennia with `pip install`, the library folder will be installed deep inside your Python installation; you are better off [looking at it on github](github:evennia). If you cloned it, you should have an `evennia` folder to look into.
If you cloned the repo or read the code on `github` you'll find this being the outermost structure:
You'll find this being the outermost structure:
evennia/
bin/
@ -46,7 +38,7 @@ the _actual_ library, the thing covered by the API auto-docs and what you get wh
> The `evennia/docs/` folder contains the sources for this documentation. See
> [contributing to the docs](../../../Contributing-Docs.md) if you want to learn more about how this works.
This the the structure of the Evennia library:
This is the structure of the Evennia library:
- evennia
- [`__init__.py`](../../../Evennia-API.md#shortcuts) - The "flat API" of Evennia resides here.
@ -76,22 +68,32 @@ The `__init__.py` file is a special Python filename used to represent a Python '
```
While all the actual Evennia code is found in the various folders, the `__init__.py` represents the entire
package `evennia`. It contains "shortcuts" to code that is actually located elsewhere. Most of these shortcuts
are listed if you [scroll down a bit](../../../Evennia-API.md) on the Evennia-API page.
While all the actual Evennia code is found in the various folders, the `__init__.py` represents the entire package `evennia`. It contains "shortcuts" to code that is actually located elsewhere. Most of these shortcuts are listed if you [scroll down a bit](../../../Evennia-API.md) on the Evennia-API page.
## An example of exploring the library
In the previous lesson we took a brief look at `mygame/typeclasses/objects` as an example of a Python module. Let's
open it again. Inside is the `Object` class, which inherits from `DefaultObject`.
Near the top of the module is this line:
In the [previous lesson](./Beginner-Tutorial-Python-classes-and-objects.md#on-classes-and-objects) we took a brief look at `mygame/typeclasses/objects` as an example of a Python module. Let's open it again.
```python
"""
module docstring
"""
from evennia import DefaultObject
class Object(DefaultObject):
"""
class docstring
"""
pass
```
We have the `Object` class, which inherits from `DefaultObject`. Near the top of the module is this line:
from evennia import DefaultObject
We want to figure out just what this DefaultObject offers. Since this is imported directly from `evennia`, we
are actually importing from `evennia/__init__.py`.
We want to figure out just what this DefaultObject offers. Since this is imported directly from `evennia`, we are actually importing from `evennia/__init__.py`.
[Look at Line 159](github:evennia/__init__.py#159) of `evennia/__init__.py` and you'll find this line:
[Look at Line 160](github:evennia/__init__.py#L160) of `evennia/__init__.py` and you'll find this line:
from .objects.objects import DefaultObject
@ -100,17 +102,19 @@ are actually importing from `evennia/__init__.py`.
The first full-stop in `from .objects.objects ...` means that we are importing from the current location. This is called a `relative import`. By comparison, `from evennia.objects.objects` is an `absolute import`. In this particular case, the two would give the same result.
```
> You can also look at [the right section of the API frontpage](../../../Evennia-API.md#typeclasses) and click through
> to the code that way.
> You can also look at [the right section of the API frontpage](../../../Evennia-API.md#typeclasses) and click through to the code that way.
The fact that `DefaultObject` is imported into `__init__.py` here is what makes it possible to also import
it as `from evennia import DefaultObject` even though the code for the class is not actually here.
The fact that `DefaultObject` is imported into `__init__.py` here is what makes it possible to also import it as `from evennia import DefaultObject` even though the code for the class is not actually here.
So to find the code for `DefaultObject` we need to look in `evennia/objects/objects.py`. Here's how
to look it up in the docs:
So to find the code for `DefaultObject` we need to look in `evennia/objects/objects.py`. Here's how to look it up in the docs:
1. Open the [API frontpage](../../../Evennia-API.md)
2. Locate the link to [evennia.objects.objects](../../../api/evennia.objects.objects.md) and click on it.
3 You are now in the python module. Scroll down (or search in your web browser) to find the `DefaultObject` class.
4 You can now read what this does and what methods are on it. If you want to see the full source, click the
\[source\] link next to it.
3. You are now in the python module. Scroll down (or search in your web browser) to find the `DefaultObject` class.
4. You can now read what this does and what methods are on it. If you want to see the full source, click the \[source\] link next to it.
## Conclusions
This is an important lesson. It teaches you how to find information for yourself. Knowing how to follow the class inheritance tree and navigate to things you need is a big part in learning a new library like Evennia.
Next we'll start to make use of what we have learned so far and combine it with the building blocks provided by Evennia.