From c9e4f1aaa6b88c7b9d330f5d5f54e4e7a1c3e4fa Mon Sep 17 00:00:00 2001 From: Griatch Date: Tue, 7 Jul 2020 00:18:47 +0200 Subject: [PATCH] Add new src: link alias --- docs/source/Evennia-API.md | 1 + .../Starting/Part1/Evennia-API-Overview.md | 94 ++++++++++++++++--- docs/source/conf.py | 14 +++ 3 files changed, 94 insertions(+), 15 deletions(-) diff --git a/docs/source/Evennia-API.md b/docs/source/Evennia-API.md index 7088bdae53..60f558f281 100644 --- a/docs/source/Evennia-API.md +++ b/docs/source/Evennia-API.md @@ -19,6 +19,7 @@ ## Shortcuts Evennia's 'flat API' has shortcuts to common tools, available by only importing `evennia`. +The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__.py) ### Main config diff --git a/docs/source/Howto/Starting/Part1/Evennia-API-Overview.md b/docs/source/Howto/Starting/Part1/Evennia-API-Overview.md index 720b5ab26a..168f6705c4 100644 --- a/docs/source/Howto/Starting/Part1/Evennia-API-Overview.md +++ b/docs/source/Howto/Starting/Part1/Evennia-API-Overview.md @@ -12,34 +12,36 @@ we have used several resources from the Evennia library. Some examples: - `evennia.default_cmds` holding references to all default Command classes like `look`, `dig` and so on. Evennia has a lot of resources to help you make your game. We have just given a selection of them for you to try -out so far (and we'll show off many more in the lessons to come). Now we'll teach you how find them +out so far (and we'll show off many more in the lessons to come). Now we'll teach you how to find them for yourself. ## Exploring the API The Evennia _API_ ([Application Programming Interface](https://en.wikipedia.org/wiki/Application_programming_interface)) is what -you use to access things inside the `evennia` package. You can examine this in many ways: +you use to access things inside the `evennia` package. -- The easiest is to browse the [API auto-docs](../../../Evennia-API) [api](api:evennia) coming with this very documentation. This is built - automatically from the latest sources. The auto-docs give you each class, function and method along with the - docstring and everything you need to use that resource. If you want to go deeper you can also click the `[src]` - link next to e.g. a class to see its full python code. The documentation is also searchable. -- You can 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. -- You can also 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 +Open the [API frontpage](../../../Evennia-API). 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. + +### Browsing the code + +You can 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. + +You can also 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/Extended-Installation) if you want to do this. The short of is to install `git` and run git clone https://github.com/evennia/evennia.git In the terminal/console you can search for anything using `git` (make sure you are inside the repo): - git grep "class DefaultObject" + git grep -n "class DefaultObject" - will quickly tell you where the DefaultObject class is defined. - -### Side note for those reading the code directly (optional) + will quickly tell you which file the DefaultObject class is defined and on which line. If you read the code on `github` or cloned the repo yourself, you will find this being the outermost folder structure: @@ -59,7 +61,69 @@ installation. It's not something we'll bother with for this tutorial. > The `evennia/docs/` folder contains, well, this documentation. See [contributing to the docs](../../../Contributing-Docs) if you want to learn more about how this works. -## Overview of the library +## Overview of the `evennia` root package + +``` + evennia/ + __init__.py + settings_default.py + accounts/ + commands/ + comms/ + game_template/ + help/ + locale/ + locks/ + objects/ + prototypes/ + scripts/ + server/ + typeclasses/ + utils/ + web/ +``` + +```sidebar:: __init__.py + + The `__init__.py` file is a special Python filename used to represent a Python 'package'. + When you import `evennia` on its own, you import this file. When you do `evennia.foo` Python will + first look for a property `.foo` in `__init__.py` and then for a module or folder in the same + location. + +``` +While all the actual Evennia code is found in the various folders, the `__init__.py` contains "shortcuts" +to useful things you will often need. This allows you to do things like `from evennia import DefaultObject` +even though the `DefaultObject` is not actually defined there. Let's see how that works: + +[Look at Line 189](evennia/__init__.py#L189) of `evennia/__init__.py` and you'll find this line: + +```python + # ... + from .objects.objects import DefaultObject + # ... +``` + +```sidebar:: Relative and absolute imports + + 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. +``` + +Since `DefaultObject` is imported into `__init__.py`, it means we can do +`from evennia import DefaultObject` even though the code for it is not actually here. + +So if we want to find the code for `DefaultObject` we need to look in +`evennia/objects/objects.py`. Here's how to look it up in these docs: + +1. Open the [API frontpage](../../../Evennia-API) +2. Locate the link to [evennia.objects](api:evennia.objects) and click on it. +3. Click through to [evennia.objects.objects](api:evennia.objects.objects). +4. You are now in the python module. Scroll down (or search in your web browser) to find the `DefaultObject` class. +5. You can now read what this does and what methods are on it. If you want to see the full source, click the + \[[source](src:evennia.objects.objects#DefaultObject)\] link. + diff --git a/docs/source/conf.py b/docs/source/conf.py index 26d758fbbb..65325d8446 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -122,6 +122,7 @@ def url_resolver(url): githubstart = "github:" apistart = "api:" choose_issue = "github:issue" + sourcestart = "src:" if url.endswith(choose_issue): return _github_issue_choose @@ -137,6 +138,19 @@ def url_resolver(url): path = "../".join("" for _ in range(depth)) urlpath = path + "api/" + url[ind + len(apistart):] + ".html" return urlpath + elif sourcestart in url: + ind = url.index(sourcestart) + depth = url[:ind].count("/") + 1 + path = "../".join("" for _ in range(depth)) + + modpath, *inmodule = url[ind + len(sourcestart):].rsplit("#", 1) + modpath = "/".join(modpath.split(".")) + inmodule = "#" + inmodule[0] if inmodule else "" + modpath = modpath + ".html" + inmodule + + urlpath = path + "_modules/" + modpath + return urlpath + return url