Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-22 15:56:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Doc test updates

Browse source
This commit is contained in:
Griatch 2020-10-13 18:48:21 +02:00
parent fcb5026e0c
commit 7e6fc22dcc
6 changed files with 930 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/Makefile
View file

@ -71,7 +71,7 @@ _multiversion-autodoc-index:
make _clean_api_index
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE)
make _reformat_apidoc_headers
git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index."
git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index." | :
_html-build:
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"

701
docs/source/Contributing-Docs.md Normal file
View file

@ -0,0 +1,701 @@
# Contributing to Evennia Docs
```warning::
WARNING: This system is still WIP and many things are bound to change!
```
Contributing to the docs is is like [contributing to the rest of Evennia][contributing]: Check out the branch of Evennia you want to edit the documentation for. Create your
own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it!
The documentation source files are `*.md` (Markdown) files found in `evennia/docs/source/`.
Markdown files are simple text files that can be edited with a normal text editor. They can also
contain raw HTML directives (but that is very rarely needed). They primarly use
the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help.
## Source file structure
The sources are organized into several rough categories, with only a few administrative documents
at the root of `evennia/docs/source/`. The folders are named in singular form since they will
primarily be accessed as link refs (e.g. `Component/Account`)
- `source/Components/` are docs describing separate Evennia building blocks, that is, things
that you can import and use. This extends and elaborates on what can be found out by reading
the api docs themselves. Example are documentation for `Accounts`, `Objects` and `Commands`.
- `source/Concepts/` describes how larger-scale features of Evennia hang together - things that
can't easily be broken down into one isolated component. This can be general descriptions of
how Models and Typeclasses interact to the path a message takes from the client to the server
and back.
- `source/Setup/` holds detailed docs on installing, running and maintaining the Evennia server and
the infrastructure around it.
- `source/Coding/` has help on how to interact with, use and navigate the Evennia codebase itself.
This also has non-Evennia-specific help on general development concepts and how to set up a sane
development environment.
- `source/Contribs/` holds documentation specifically for packages in the `evennia/contribs/` folder.
Any contrib-specific tutorials will be found here instead of in `Howtos`
- `source/Howtos/` holds docs that describe how to achieve a specific goal, effect or
result in Evennia. This is often on a tutorial or FAQ form and will refer to the rest of the
documentation for further reading.
- `source/Howtos/Starting/` holds all documents part of the initial tutorial sequence.
Other files and folders:
- `source/api/` contains the auto-generated API documentation as `.rst` files. Don't edit these
files manually, your changes will be lost. To refer to these files, use `api:` followed by
the Python path, for example `[rpsystem contrib](api:evennia.contrib.rpsystem)`.
- `source/_templates` and `source/_static` should not be modified unless adding a new doc-page
feature or changing the look of the HTML documentation.
- `conf.py` holds the Sphinx configuration. It should usually not be modified except to update
the Evennia version on a new branch.
## Building the docs locally
The sources in `evennia/docs/source/` are built into a documentation using the
[Sphinx][sphinx] static generator system. To do this locally you need to use a
system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking
that, you could in principle also run the sphinx build-commands manually - read
the `evennia/docs/Makefile` to see which commands are run by the `make`-commands
referred to in this document.
You don't necessarily _have_ to build the docs locally to contribute. Markdown is
not hard and is very readable on its raw text-form.
You can furthermore get a good feel for how things will look using a
Markdown-viewer like [Grip][grip]. Editors like [ReText][retext] or IDE's like
[PyCharm][pycharm] also have native Markdown previews. Building the docs locally is
however the only way to make sure the outcome is exactly as you expect. The process
will also find any mistakes you made, like making a typo in a link.
### Building only the main documentation
This is the fastest way to compile and view your changes. It will only build
the main documentation pages and not the API auto-docs or versions. All is
done in your terminal/console.
- (Optional, but recommended): Activate a virtualenv with Python 3.7.
- `cd` to into the `evennia/docs` folder.
- Install the documentation-build requirements:
```
make install
or
pip install -r requirements.txt
```
- Next, build the html-based documentation (re-run this in the future to build your changes):
```
make quick
```
- Note any errors from files you have edited.
- The html-based documentation will appear in the new
folder `evennia/docs/build/html/`.
- Use a web browser to open `file://<path-to-folder>/evennia/docs/build/html/index.html` and view
the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn't
build them!
### Building the main documentation and API docs
The full documentation includes both the doc pages and the API documentation
generated from the Evennia source. For this you must install Evennia and
initialize a new game with a default database (you don't need to have any server
running)
- It's recommended that you use a virtualenv. Install your cloned version of Evennia into
by pointing to the repo folder (the one containing `/docs`):
```
pip install -e evennia
```
- Make sure you are in the parent folder _containing_ your `evennia/` repo (so _two_ levels
up from `evennia/docs/`).
- Create a new game folder called exactly `gamedir` at the same level as your `evennia`
repo with
```
evennia --init gamedir
```
- Then `cd` into it and create a new, empty database. You don't need to start the
game or do any further changes after this.
```
evennia migrate
```
- This is how the structure should look at this point:
```
(top)
|
----- evennia/ (the top-level folder, containing docs/)
|
----- gamedir/
```
(If you are already working on a game, you may of course have your 'real' game folder there as
well. We won't touch that.)
- Go to `evennia/docs/` and install the doc-building requirements (you only need to do this once):
```
make install
or
pip install -r requirements.txt
```
- Finally, build the full documentation, including the auto-docs:
```
make local
```
- The rendered files will appear in a new folder `evennia/docs/build/html/`.
Note any errors from files you have edited.
- Point your web browser to `file://<path-to-folder>/evennia/docs/build/html/index.html` to
view the full docs.
#### Building with another gamedir
If you for some reason want to use another location of your `gamedir/`, or want it
named something else (maybe you already use the name 'gamedir' for your development ...),
you can do so by setting the `EVGAMEDIR` environment variable to the absolute path
of your alternative game dir. For example:
```
EVGAMEDIR=/my/path/to/mygamedir make local
```
### Building for release
The full Evennia documentation contains docs from many Evennia
versions, old and new. This is done by pulling documentation from Evennia's old release
branches and building them all so readers can choose which one to view. Only
specific official Evennia branches will be built, so you can't use this to
build your own testing branch.
- All local changes must have been committed to git first, since the versioned
docs are built by looking at the git tree.
- To build for local checking, run (`mv` stands for "multi-version"):
```
make mv-local
```
This is as close to the 'real' version of the docs as you can get locally. The different versions
will be found under `evennia/docs/build/versions/`. During deploy a symlink `latest` will point
to the latest version of the docs.
#### Release
Releasing the official docs requires git-push access the the Evennia `gh-pages` branch
on `github`. So there is no risk of you releasing your local changes accidentally.
- To deploy docs in two steps
```
make mv-local
make deploy
```
- If you know what you are doing you can also do build + deploy in one step:
```
make release
```
After deployment finishes, the updated live documentation will be
available at https://evennia.github.io/evennia/latest/.
# Editing syntax
The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown
supports a
few alternative forms for some of these, we try to stick to the below forms for consistency.
### Italic/Bold
We generally use underscores for italics and double-asterisks for bold:
- `_Italic text_` - _Italic text_
- `**Bold Text**` - **Bold text**
### Headings
We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get
smaller and smaller font).
- `# Heading`
- `## SubHeading`
- `### SubSubHeading`
- `#### SubSubSubHeading`
> Don't use the same heading/subheading name more than once in one page. While Markdown
does not prevent it, it will make it impossible to refer to that heading uniquely.
The Evennia documentation preparser will detect this and give you an error.
### Lists
One can create both bullet-point lists and numbered lists:
```
- first bulletpoint
- second bulletpoint
- third bulletpoint
```
- first bulletpoint
- second bulletpoint
- third bulletpoint
```
1. Numbered point one
2. Numbered point two
3. Numbered point three
```
1. Numbered point one
2. Numbered point two
3. Numbered point three
### Blockquotes
A blockquote will create an indented block. It's useful for emphasis and is
added by starting one or more lines with `>`. For 'notes' you can also use
an explicit [Note](#Note).
```
> This is an important
> thing to remember.
```
> Note: This is an important
> thing to remember.
### Links
- `[linktext](url_or_ref)` - gives a clickable link [linktext][linkdemo].
The `url_or_ref` can either be a full `http://...` url or an internal _reference_. For example, use
`[my document](My-Document)` to link to the document `evennia/docs/source/My-Document.md`. Avoid
using
full `http://` linking unless really referring to an external resource.
- `[linktext](ref#heading-name)`
You can point to sub-sections (headings) in a document by using a single `#` and the name of the
heading, replacing spaces with dashes. So to refer to a heading `## Cool Stuff` inside `My-Document`
would be a link `[cool stuff](My-Document#Cool-Stuff)`. This is why headings must be uniquely named
within on document.
- `[linktext][linkref]` - refer to a reference defined later in the document.
Urls can get long and if you are using the same url in many places it can get a little cluttered. So
you can also put the url as a 'footnote' at the end of your document
and refer to it by putting your reference within square brackets `[ ]`. Here's an example:
```
This is a [clickable link][mylink]. This is [another link][1].
...
[mylink]: http://...
[1]: My-Document
```
#### Special references
The Evennia documentation supports some special reference shortcuts in links:
##### Github online repository
- `github:` - a shortcut for the full path to the Evennia repository on github. This must be given
with forward-slashes and include the `.py` file ending. It will refer to the `master` branch by default:
[link to objects.py](github:evennia/objects/objects.py)
This will remap to https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py.
- To refer to the `develop` branch, start the url with `develop/`:
[link to objects.py](github:develop/evennia/objects/objects.py)
##### API
- `api:` - references a path in the api documentation. This is specified as a Python-path:
[link to api for objects.py](api:evennia.objects)
This will create a link to the auto-generated `evennia/source/api/evennia.objects.rst` document.
Since api-docs are generated alongside the documentation, this will always be the api docs for
the current version/branch of the docs.
##### Bug reports/feature request
- `github:issue` - links to the github issue selection page, where the user can choose which type of
issue to create.
If you find a problem, make a [bug report](github:issue)!
This will generate a link to https://github.com/evennia/evennia/issues/new/choose.
### Verbatim text
It's common to want to mark something to be displayed verbatim - just as written - without any
Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes
`verbatim text`.
If you want to put the verbatim text on its own line, you can do so easily by simply indenting
it 4 spaces (add empty lines on each side for readability too):
```
This is normal text
This is verbatim text
This is normal text
```
Another way is to use triple-backticks:
````
```
Everything within these backticks will be verbatim.
```
````
### Code blocks
A special case is code examples - we want them to get code-highlighting for readability. This is
done by using
the triple-backticks and specify which language we use:
````
```python
def a_python_func(x):
return x * x
```
````
```python
def a_python_func(x):
return x * x
```
### ReST blocks
Markdown is easy to read and use. But while it does most of what we need, there are some things it's
not quite as expressive as it needs to be. For this we need to fall back to the [ReST][ReST] markup
language which the documentation system uses under the hood. This is done by specifying `eval_rst`
as the name of the `language` of a literal block:
````
```eval_rst
This will be evaluated as ReST.
All content must be indented.
```
````
There is also a short-hand form for starting a [ReST directive][ReST-directives] without need for
`eval_rst`:
````
```directive:: possible-option
Content *must* be indented for it to be included in the directive.
New lines are ignored, empty lines starts a new paragraph.
```
````
Within a ReST block, one must use Restructured Text syntax, which is not the same as Markdown.
- Single backticks around text makes it _italic_.
- Double backticks around text makes it `verbatim`.
- A link is written within back-ticks, with an underscore at the end:
`python <www.python.org>`_
[Here is a ReST formatting cheat sheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html).
Below are examples of ReST-block structures.
#### Note
This kind of note may pop more than doing a `> Note: ...`. Contrary to a
[blockquote](#Blockquotes), the end result will not be indented.
````
```note::
Remember that you have to indent this content for it to be part of the note.
```
````
```note::
Remember that you have to indent this content for it to be part of the note.
```
#### Important
This is for particularly important and visible notes.
````
```important::
This is important because it is!
```
````
```important::
This is important because it is!
```
#### Warning
A warning block is used to draw attention to particularly dangerous things, or features easy to
mess up.
````
```warning::
Be careful about this ...
```
````
```warning::
Be careful about this ...
```
#### Version changes and deprecations
These will show up as one-line warnings that suggest an added, changed or deprecated
feature beginning with particular version.
````
```versionadded:: 1.0
```
````
```versionadded:: 1.0
```
````
```versionchanged:: 1.0
How the feature changed with this version.
```
````
```versionchanged:: 1.0
How the feature changed with this version.
```
````
```deprecated:: 1.0
```
````
```deprecated:: 1.0
```
#### Sidebar
This will display an informative sidebar that floats to the side of regular content. This is useful
for example to remind the reader of some concept relevant to the text.
````
```sidebar:: Things to remember
- There can be bullet lists
- in here.
Headers:
with indented blocks like this
Will end up:
as full sub-headings in the sidebar.
```
````
```sidebar:: Things to remember
- There can be bullet lists
- in here.
Headers:
with indented blocks like this
Will end up:
as full sub-headings in the sidebar.
```
Remember that for ReST-directives, the content within the triple-backticks _must_ be indented to
some degree or the content will just appear outside of the directive as regular text.
If wanting to make sure to have the next header appear on a row of its own, one can embed
a plain HTML string in the markdown like so:
```html
<div style="clear: right;"></div>
```
<div style="clear: right;"></div>
#### Tables
A table is specified using [ReST table syntax][ReST-tables] (they don't need to be indented):
````
```eval_rst
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
```
````
```eval_rst
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
```
or the more flexible but verbose
````
```eval_rst
+------------------------+------------+----------+----------+
| Header row, column 3 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
```
````
```eval_rst
+------------------------+------------+----------+----------+
| Header row, column 3 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
```
#### A more flexible code block
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
can also specify the code block explicitly in `ReST` for more flexibility.
It also provides a link to the code block, identified by its name.
````
```code-block:: python
:linenos:
:emphasize-lines: 1-2,8
:caption: An example code block
:name: A full code block example
from evennia import Command
class CmdEcho(Command):
"""
Usage: echo <arg>
"""
key = "echo"
def func(self):
self.caller.msg(self.args.strip())
```
````
```code-block:: python
:linenos:
:emphasize-lines: 1-2,8
:caption: An example code block
:name: A full code block example
from evennia import Command
class CmdEcho(Command):
"""
Usage: echo <arg>
"""
key = "echo"
def func(self):
self.caller.msg(self.args.strip())
```
Here, `:linenos:` turns on line-numbers and `:emphasize-lines:` allows for emphasizing certain lines
in a different color. The `:caption:` shows an instructive text and `:name:` is used to reference
this
block through the link that will appear (so it should be unique for a give document).
> The default markdown syntax will actually generate a code-block ReST instruction like this
> automatically for us behind the scenes. But the automatic generation can't know things like emphasize-
lines or captions since that's not a part of the Markdown specification.
## Code documentation
The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting,
including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's
a good idea to end with four dashes `----`. This will create a visible line between the documentation and the
class/function docs to follow. See for example [the Traits docs](api:evennia.contrib.traits).
All non-private classes, methods and functions must have a Google-style docstring, as per the
[Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted
into pretty api docs.
## Technical
Evennia leverages [Sphinx][sphinx] with the [recommonmark][recommonmark] extension, which allows us
to write our
docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github) rather
than ReST.
The recommonmark extension however also allows us to use ReST selectively in the places were it is
more
expressive than the simpler (but much easier) Markdown.
For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon]
extension
to understand our friendly Google-style docstrings used in classes and functions etc.
[sphinx](https://www.sphinx-doc.org/en/master/)
[recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html)
[commonmark](https://spec.commonmark.org/current/)
[commonmark-help](https://commonmark.org/help/)
[sphinx-autodoc](http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc)
[sphinx-napoleon](http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
[getting-started]: Setup/Setup-Quickstart
[contributing]: ./Contributing
[ReST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
[ReST-tables](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables)
[ReST-directives](https://www.sphinx-doc.org/en/master/usage/restruturedtext/directives.html)
[Windows-WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
[linkdemo]: #Links
[retext](https://github.com/retext-project/retext)
[grip](https://github.com/joeyespo/grip)
[pycharm](https://www.jetbrains.com/pycharm/)

219
docs/source/_templates/layout.html
View file

@ -1 +1,218 @@
{%- extends "!layout.html" %}
{#
basic/layout.html
~~~~~~~~~~~~~~~~~
Master layout template for Sphinx themes.
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- block doctype -%}{%- if html5_doctype %}
<!DOCTYPE html>
{%- else %}
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
{%- endif %}{%- endblock %}
{%- set reldelim1 = reldelim1 is not defined and ' &#187;' or reldelim1 %}
{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
(sidebars != []) %}
{%- set url_root = pathto('', 1) %}
{# XXX necessary? #}
{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
{%- if not embedded and docstitle %}
{%- set titlesuffix = " &#8212; "|safe + docstitle|e %}
{%- else %}
{%- set titlesuffix = "" %}
{%- endif %}
{%- macro relbar() %}
<div class="related" role="navigation" aria-label="related navigation">
<h3>{{ _('Navigation') }}</h3>
<ul>
{%- for rellink in rellinks %}
<li class="right" {% if loop.first %}style="margin-right: 10px"{% endif %}>
<a href="{{ pathto(rellink[0])|e }}" title="{{ rellink[1]|striptags|e }}"
{{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
{%- if not loop.first %}{{ reldelim2 }}{% endif %}</li>
{%- endfor %}
{%- block rootrellink %}
<li class="nav-item nav-item-0"><a href="{{ pathto(master_doc)|e }}">{{ shorttitle|e }} {{ release }}</a>{{ reldelim1 }}</li>
{%- endblock %}
{%- for parent in parents %}
<li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
{%- endfor %}
<li class="nav-item nav-item-this"><a href="{{ link|e }}">{{ title }}</a></li>
{%- block relbaritems %} {% endblock %}
</ul>
</div>
{%- endmacro %}
{%- macro sidebar() %}
{%- if render_sidebar %}
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
{%- block sidebarlogo %}
{%- if logo %}
<p class="logo"><a href="{{ pathto(master_doc)|e }}">
<img class="logo" src="{{ pathto('_static/' + logo, 1)|e }}" alt="Logo"/>
</a></p>
{%- endif %}
{%- endblock %}
{%- if sidebars != None %}
{#- new style sidebar: explicitly include/exclude templates #}
{%- for sidebartemplate in sidebars %}
{%- include sidebartemplate %}
{%- endfor %}
{%- else %}
{#- old style sidebars: using blocks -- should be deprecated #}
{%- block sidebartoc %}
{%- include "localtoc.html" %}
{%- endblock %}
{%- block sidebarrel %}
{%- include "relations.html" %}
{%- endblock %}
{%- block sidebarsourcelink %}
{%- include "sourcelink.html" %}
{%- endblock %}
{%- if customsidebar %}
{%- include customsidebar %}
{%- endif %}
{%- block sidebarsearch %}
{%- include "searchbox.html" %}
{%- endblock %}
{%- endif %}
</div>
</div>
{%- endif %}
{%- endmacro %}
{%- macro script() %}
<script id="documentation_options" data-url_root="{{ pathto('', 1) }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
{%- for js in script_files %}
{{ js_tag(js) }}
{%- endfor %}
{%- endmacro %}
{%- macro css() %}
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1)|e }}" type="text/css" />
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
{%- for css in css_files %}
{%- if css|attr("filename") %}
{{ css_tag(css) }}
{%- else %}
<link rel="stylesheet" href="{{ pathto(css, 1)|e }}" type="text/css" />
{%- endif %}
{%- endfor %}
{%- endmacro %}
{%- if html_tag %}
{{ html_tag }}
{%- else %}
<html{% if not html5_doctype %} xmlns="http://www.w3.org/1999/xhtml"{% endif %}{% if language is not none %} lang="{{ language }}"{% endif %}>
{%- endif %}
<head>
{%- if not html5_doctype and not skip_ua_compatible %}
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
{%- endif %}
{%- if use_meta_charset or html5_doctype %}
<meta charset="{{ encoding }}" />
{%- else %}
<meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
{%- endif %}
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
{{- metatags }}
{%- block htmltitle %}
<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
{%- endblock %}
{%- block css %}
{{- css() }}
{%- endblock %}
{%- if not embedded %}
{%- block scripts %}
{{- script() }}
{%- endblock %}
{%- if pageurl %}
<link rel="canonical" href="{{ pageurl|e }}" />
{%- endif %}
{%- if use_opensearch %}
<link rel="search" type="application/opensearchdescription+xml"
title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
href="{{ pathto('_static/opensearch.xml', 1) }}"/>
{%- endif %}
{%- if favicon %}
<link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1)|e }}"/>
{%- endif %}
{%- endif %}
{%- block linktags %}
{%- if hasdoc('about') %}
<link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
{%- endif %}
{%- if hasdoc('genindex') %}
<link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
{%- endif %}
{%- if hasdoc('search') %}
<link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
{%- endif %}
{%- if hasdoc('copyright') %}
<link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
{%- endif %}
{%- if next %}
<link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
{%- endif %}
{%- if prev %}
<link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
{%- endif %}
{%- endblock %}
{%- block extrahead %} {% endblock %}
</head>
{%- block body_tag %}<body>{% endblock %}
{%- block header %}{% endblock %}
{%- block relbar1 %}{{ relbar() }}{% endblock %}
{%- block content %}
{%- block sidebar1 %} {# possible location for sidebar #} {% endblock %}
<div class="document">
{%- block document %}
<div class="documentwrapper">
{%- if render_sidebar %}
<div class="bodywrapper">
{%- endif %}
<div class="body" role="main">
{% block body %} {% endblock %}
<div class="clearer"></div>
</div>
{%- if render_sidebar %}
</div>
{%- endif %}
</div>
{%- endblock %}
{%- block sidebar2 %}{{ sidebar() }}{% endblock %}
<div class="clearer"></div>
</div>
{%- endblock %}
{%- block relbar2 %}{{ relbar() }}{% endblock %}
{%- block footer %}
<div class="footer" role="contentinfo">
{%- if show_copyright %}
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e %}&#169; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
{%- else %}
{% trans copyright=copyright|e %}&#169; Copyright {{ copyright }}.{% endtrans %}
{%- endif %}
{%- endif %}
{%- if last_updated %}
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
{%- endif %}
{%- if show_sphinx %}
{% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
{%- endif %}
</div>
{%- endblock %}
</body>
</html>

2
docs/source/conf.py
View file

@ -76,7 +76,7 @@ html_sidebars = {
}
html_favicon = "_static/images/favicon.ico"
html_logo = "_static/images/evennia_logo.png"
html_short_title = f"Evennia {release}"
html_short_title = "Evennia"
# HTML syntax highlighting style
pygments_style = "sphinx"

14
docs/source/index.md
View file

@ -1,10 +1,11 @@
# VERSION WARNING
```important::
> This is the v0.95 documentation of Evennia, originally converted from the old
> [evennia wiki](https://github.com/evennia/evennia/wiki/) at 2020-10-11 18:06:03.062022.
> While we will fix outright mistakes, minor typos and visual conversion issues will _not_ be
> addressed in this version.
> A new and refactored version of the docs is being prepared for version 1.0 of Evennia.
This is the v0.9.5 documentation of Evennia, originally converted from the old
`evennia wiki <https://github.com/evennia/evennia/wiki>`_ at 2020-10-11 18:06:03.062022.
While we will fix outright mistakes, minor typos and visual conversion issues will **not** be
addressed in this version.
A new and refactored version of the docs is being prepared for version 1.0 of Evennia.
```
# Evennia Documentation
@ -22,6 +23,7 @@ time.
- The [Builder Docs](./Builder-Docs) helps for starting to build a game world using Evennia.
- The [Developer Central](./Developer-Central) describes how Evennia works and is used by coders.
- The [Tutorials & Examples](./Tutorials) contains help pages on a step-by-step or tutorial format.
- The [Documentation-Contributing](./Contributing-Docs) page helps with how to write and contribute to these docs.
- The [API](./Evennia-API) documentation is created from the latest source code.
- The [TOC](./toc) lists all regular documentation pages.

1
docs/source/toc.md
View file

@ -38,6 +38,7 @@
- [./Connection Screen](./Connection-Screen)
- [./Continuous Integration](./Continuous-Integration)
- [./Contributing](./Contributing)
- [./Contributing Docs](./Contributing-Docs)
- [./Coordinates](./Coordinates)
- [./Custom Protocols](./Custom-Protocols)
- [./Customize channels](./Customize-channels)