From 31306f5b22994c33b4da6b8604290187fdbac25e Mon Sep 17 00:00:00 2001
From: Griatch <griatch@gmail.com>
Date: Sun, 14 Jun 2020 21:45:37 +0200
Subject: [PATCH] Add doc-contribution page, toctree-creation mechanism

---
 docs/pylib/copy_from_wiki.py     |  19 +-
 docs/pylib/create_toctree.py     |  40 ++
 docs/source/Contributing-Docs.md | 632 +++++++++++++++++++++++++++++++
 docs/source/conf.py              |  10 +-
 docs/source/index.md             |  74 +---
 docs/source/toc.md               | 283 +++++++-------
 6 files changed, 833 insertions(+), 225 deletions(-)
 create mode 100644 docs/pylib/create_toctree.py
 create mode 100644 docs/source/Contributing-Docs.md

diff --git a/docs/pylib/copy_from_wiki.py b/docs/pylib/copy_from_wiki.py
index 151eb37b3f..1c8dc85fe3 100644
--- a/docs/pylib/copy_from_wiki.py
+++ b/docs/pylib/copy_from_wiki.py
@@ -15,7 +15,7 @@ We also need to build the toc-tree and should do so automatically for now.
 
 import glob
 import re
-import datetime 
+import datetime
 
 _RE_MD_LINK = re.compile(r"\[(?P<txt>[\w -\[\]]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U)
 _RE_REF_LINK = re.compile(r"\[[\w -\[\]]*?\]\(.+?\)", re.I + re.S + re.U)
@@ -32,13 +32,13 @@ _INDEX_PREFIX = f"""
 
 # VERSION WARNING
 
-> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the 
+> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the
 > [evennia wiki](https://github.com/evennia/evennia/wiki/) at {datetime.datetime.now()}.
-> There are known conversion issues which  will _not_ be addressed in this version - refer to 
+> There are known conversion issues which  will _not_ be addressed in this version - refer to
 > the original wiki if you have trouble.
 >
 > Manual conversion and cleanup will instead happen during development of the upcoming v1.0
-> version of this static documentation. 
+> version of this static documentation.
 
 """
 
@@ -202,7 +202,6 @@ def _sub_link(match):
     return f"[{txt}]({url})"
 
 def create_toctree(files):
-
     with open("../source/toc.md", "w") as fil:
         fil.write("# Toc\n")
 
@@ -221,7 +220,7 @@ def convert_links(files, outdir):
 
     for inpath in files:
 
-        is_index = False 
+        is_index = False
         outfile = inpath.rsplit('/', 1)[-1]
         if outfile == "Home.md":
             outfile = "index.md"
@@ -235,7 +234,7 @@ def convert_links(files, outdir):
             text = fil.read()
 
             if is_index:
-                text = _INDEX_PREFIX + text 
+                text = _INDEX_PREFIX + text
                 lines = text.split("\n")
                 lines = (lines[:-11]
                          + [" - The [TOC](toc) lists all regular documentation pages.\n\n"]
@@ -256,6 +255,6 @@ def convert_links(files, outdir):
             fil.write(text)
 
 if __name__ == "__main__":
-
-    create_toctree(_INFILES)
-    convert_links(_INFILES, _OUTDIR)
+    print("This should not be run on develop files, it would overwrite changes.")
+    # create_toctree(_INFILES)
+    # convert_links(_INFILES, _OUTDIR)
diff --git a/docs/pylib/create_toctree.py b/docs/pylib/create_toctree.py
new file mode 100644
index 0000000000..86b752955b
--- /dev/null
+++ b/docs/pylib/create_toctree.py
@@ -0,0 +1,40 @@
+"""
+Build a TOC-tree; Sphinx requires it and this makes it easy to just
+add/build/link new files without needing to explicitly add it to a toctree
+directive somewhere.
+
+"""
+
+import glob
+from os.path import abspath, dirname, join as pathjoin, sep
+
+_SOURCEDIR = "../source/"
+_IGNORE_FILES = []
+_SOURCE_DIR = pathjoin(dirname(dirname(abspath(__file__))), "source")
+_TOC_FILE = pathjoin(_SOURCE_DIR, "toc.md")
+
+
+def create_toctree():
+    """
+    Create source/toc.md file
+    """
+    _INFILES = [path for path in glob.glob(_SOURCE_DIR + sep + "*.md")
+                if path.rsplit('/', 1)[-1] not in _IGNORE_FILES]
+    # split out the name and remove the .md extension
+    _FILENAMES = [path.rsplit("/", 1)[-1] for path in sorted(_INFILES)]
+    _FILENAMES = [path.split(".", 1)[0] for path in _FILENAMES]
+
+    with open(_TOC_FILE, "w") as fil:
+        fil.write("# Toc\n")
+
+        for ref in _FILENAMES:
+
+            if ref == "toc":
+                continue
+
+            linkname = ref.replace("-", " ")
+            fil.write(f"\n- [{linkname}]({ref}.md)")
+
+
+if __name__ == "__main__":
+    create_toctree()
diff --git a/docs/source/Contributing-Docs.md b/docs/source/Contributing-Docs.md
new file mode 100644
index 0000000000..8130622357
--- /dev/null
+++ b/docs/source/Contributing-Docs.md
@@ -0,0 +1,632 @@
+# Evennia docs
+
+Documentation for the Evennia MUD creation system.
+
+```warning::
+    WARNING: This system is still WIP and many things are bound to change!
+```
+
+The live documentation is (or will in the future be) available at 
+[https://evennia.github.io/evennia/latest](https://evennia.github.io/evennia/latest).
+
+# Editing the docs
+
+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.
+
+> Note: Don't edit the files in `source/api/`. These are auto-generated and your changes
+> will be lost.
+
+## Contributing to docs
+
+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!
+
+# Building the docs locally
+
+The sources in `evennia/docs/source/` are built into a pretty documentation using
+the [Sphinx][sphinx] static generator system. To do so locally you need to either
+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 `make`.
+
+You don't necessarily _have_ to build the docs locally to contribute.  But
+building them allows you to check for yourself that syntax is correct and that
+your change comes out looking as you expected.
+
+## Building only the main documentation
+
+If you only want to build the main documentation pages (not the API auto-docs),
+you don't need to install Evennia itself, only the documentation resources.
+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:
+
+    ```
+    make quick
+    ```
+
+- The html-based documentation will appear in the new
+  folder `evennia/docs/build/html/`. Note any errors from files you have edited.
+- 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 it
+running)
+
+- Follow the normal [Evennia Getting-Started instructions][getting-started]
+  to install Evennia into a virtualenv. Get back here once everything is installed but
+  before creating a new game.
+- Make sure you `cd` to the 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.
+
+    ```
+    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.
+
+- Make sure you are still in your virtualenv, then go to `evennia/docs/` and
+  install the doc-building requirements:
+
+    ```
+    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 as you can get locally. The different versions
+will be found under `evennia/docs/build`. 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` 
+
+# Heading
+## SubHeading
+### SubSubHeading
+
+> Don't reuse the same heading/subheading name over and over in the same document. While Markdown does not prevent
+it, it makes it impossible to link to those duplicates properly (see next section). 
+
+## 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
+
+## Notes 
+
+A note can be used to enphasise important things. It's added by starting one or more lines with `>`.
+
+```
+> 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)`.
+
+- `[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 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
+
+
+- `issue`, `bug-report`, `feature-request` - links to the same github issue select page. 
+
+        If you find a problem, make a [bug report](issue)!
+
+    This will generate a link to https://github.com/evennia/evennia/issues/new/choose.
+    
+ > For some reason these particular shortcuts gives a warning during documentation compilation. This 
+ > can be ignored. 
+
+## 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. 
+
+```
+````
+There is also a short-hand form for starting a [ReST directive][ReST-directives] without need for `eval_rst`:
+
+````
+```directive:: possible-option
+  
+  Content that *must* be indented for it to be included in the directive.
+
+  New lines are ignored except if separated by an empty line.
+```
+````
+
+See below for examples of this.
+
+#### Note
+
+This kind of note may pop even more than a normal `> note`. It may however also make the test
+feel more 'busy', so use with care.
+
+````
+```note::
+
+  Remember that ...
+
+```
+````
+```note::
+
+  Remember that ...
+
+```
+
+#### 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]:
+
+````
+```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 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: 6-7,12
+    :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: 6-7,12
+    :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. The automatic generation can't know things like emphasize-lines
+> or caption since that's not a part of the Markdown specification.
+
+# 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]: Getting-Started
+[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
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 001ac64bc9..c21d5a4185 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -126,7 +126,7 @@ def url_resolver(url):
     elif url.startswith(githubstart):
         urlpath = url[len(githubstart):]
         if not (urlpath.startswith("develop/") or urlpath.startswith("master")):
-            urlpath = "master/" + urlpath 
+            urlpath = "master/" + urlpath
         return _github_code_root + urlpath
     elif url.startswith(apistart):
         return "api/" + url[len(apistart) :] + ".html"
@@ -182,6 +182,7 @@ if not _no_autodoc:
 
         evennia._init()
 
+
 if _no_autodoc:
     exclude_patterns = ["api/*"]
 else:
@@ -223,11 +224,16 @@ napoleon_use_rtype = True
 # -- Main config setup ------------------------------------------
 # last setup steps for some plugins
 
-
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member)
     app.add_transform(AutoStructify)
 
+    # build toctree file
+    sys.path.insert(1, os.path.join(os.path.dirname(os.path.dirname(__file__)), 'docs'))
+    from docs.pylib import create_toctree
+    create_toctree.create_toctree()
+    print("Updated source/toc.md file")
+
     # custom lunr-based search
     # from docs import search
     # custom search
diff --git a/docs/source/index.md b/docs/source/index.md
index 331f595a58..33fb3cc9f2 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -9,81 +9,11 @@
 > For now you are best off using the original wiki, or the less changing v0.9.1
 > of these docs. You have been warned.
 
-```sidebar:: An important sidebar
-
-  - Extra features
-  - Another feature 
-
-  Third feature: 
-    Stuff to do 
-
-  Fourth feature:
-    Even more.
-```
-
 # Evennia Documentation
 
 This is the manual of [Evennia](http://www.evennia.com), the open source Python
-`MU*` creation system. A link to the [feature-request](issue)
-
-```note::
-
-  This is a particular note.
-
-```warning:: This is an important thing!
-  Especially this.
-```
-
-```important:: This is an interesting thing!
-
-  More text here!
-
-  And here.
-```
-
-```seealso:: This is good to look at too.
-  This in particular
-```
-
-```versionadded:: 1.0
-
-  This feature was added here
-
-```
-
-```deprecated:: 1.0
-  Use this thing instead.
-```
-
-```code-block:: python
-     :emphasize-lines: 6-7,12
-     :caption: An example code-block with everything turned on.
-     :name: Full code-block example
-
-     # Comment line
-     from evennia import Command 
-
-     class MyCommand(Command):
-       """
-       Usage: 
-          cmd x
-       """
-       key = "cmd"
-
-       def func(self):
-         self.caller.msg(self.args)
-```
-
-```markdown
-     # Comment line
-     import System
-     System.run_emphasis_line
-     # Long lines in code blocks create a auto horizontal scrollbar
-     System.exit!
-
-```
-
-<div style="clear: right;"></div>
+`MU*` creation system. Want to help improve the docs? See the page on
+[Contributing to docs](Contributing-Docs)!
 
 There is [a lengthier introduction](Evennia-Introduction) to read. You might also want to read about
 [how to get and give help](How-To-Get-And-Give-Help).
diff --git a/docs/source/toc.md b/docs/source/toc.md
index b29740aee8..9d8113fd46 100644
--- a/docs/source/toc.md
+++ b/docs/source/toc.md
@@ -1,143 +1,144 @@
 # Toc
 
-* [A voice operated elevator using events](A-voice-operated-elevator-using-events.md)
-* [API refactoring](API-refactoring.md)
-* [Accounts](Accounts.md)
-* [Add a simple new web page](Add-a-simple-new-web-page.md)
-* [Add a wiki on your website](Add-a-wiki-on-your-website.md)
-* [Adding Command Tutorial](Adding-Command-Tutorial.md)
-* [Adding Object Typeclass Tutorial](Adding-Object-Typeclass-Tutorial.md)
-* [Administrative Docs](Administrative-Docs.md)
-* [Apache Config](Apache-Config.md)
-* [Arxcode installing help](Arxcode-installing-help.md)
-* [Async Process](Async-Process.md)
-* [Attributes](Attributes.md)
-* [Banning](Banning.md)
-* [Batch Code Processor](Batch-Code-Processor.md)
-* [Batch Command Processor](Batch-Command-Processor.md)
-* [Batch Processors](Batch-Processors.md)
-* [Bootstrap & Evennia](Bootstrap-&-Evennia.md)
-* [Bootstrap Components and Utilities](Bootstrap-Components-and-Utilities.md)
-* [Builder Docs](Builder-Docs.md)
-* [Building Permissions](Building-Permissions.md)
-* [Building Quickstart](Building-Quickstart.md)
-* [Building a mech tutorial](Building-a-mech-tutorial.md)
-* [Building menus](Building-menus.md)
-* [Choosing An SQL Server](Choosing-An-SQL-Server.md)
-* [Client Support Grid](Client-Support-Grid.md)
-* [Coding FAQ](Coding-FAQ.md)
-* [Coding Introduction](Coding-Introduction.md)
-* [Coding Utils](Coding-Utils.md)
-* [Command Cooldown](Command-Cooldown.md)
-* [Command Duration](Command-Duration.md)
-* [Command Prompt](Command-Prompt.md)
-* [Command Sets](Command-Sets.md)
-* [Command System](Command-System.md)
-* [Commands](Commands.md)
-* [Communications](Communications.md)
-* [Connection Screen](Connection-Screen.md)
-* [Continuous Integration](Continuous-Integration.md)
-* [Contributing](Contributing.md)
-* [Coordinates](Coordinates.md)
-* [Custom Protocols](Custom-Protocols.md)
-* [Customize channels](Customize-channels.md)
-* [Debugging](Debugging.md)
-* [Default Command Help](Default-Command-Help.md)
-* [Default Exit Errors](Default-Exit-Errors.md)
-* [Developer Central](Developer-Central.md)
-* [Dialogues in events](Dialogues-in-events.md)
-* [Directory Overview](Directory-Overview.md)
-* [Docs refactoring](Docs-refactoring.md)
-* [Dynamic In Game Map](Dynamic-In-Game-Map.md)
-* [EvEditor](EvEditor.md)
-* [EvMenu](EvMenu.md)
-* [EvMore](EvMore.md)
-* [Evennia API](Evennia-API.md)
-* [Evennia Game Index](Evennia-Game-Index.md)
-* [Evennia Introduction](Evennia-Introduction.md)
-* [Evennia for Diku Users](Evennia-for-Diku-Users.md)
-* [Evennia for MUSH Users](Evennia-for-MUSH-Users.md)
-* [Evennia for roleplaying sessions](Evennia-for-roleplaying-sessions.md)
-* [Execute Python Code](Execute-Python-Code.md)
-* [First Steps Coding](First-Steps-Coding.md)
-* [Game Planning](Game-Planning.md)
-* [Gametime Tutorial](Gametime-Tutorial.md)
-* [Getting Started](Getting-Started.md)
-* [Glossary](Glossary.md)
-* [Grapevine](Grapevine.md)
-* [Guest Logins](Guest-Logins.md)
-* [HAProxy Config (Optional)](HAProxy-Config-(Optional).md)
-* [Help System Tutorial](Help-System-Tutorial.md)
-* [Help System](Help-System.md)
-* [Home](index.md)
-* [How To Get And Give Help](How-To-Get-And-Give-Help.md)
-* [How to connect Evennia to Twitter](How-to-connect-Evennia-to-Twitter.md)
-* [IRC](IRC.md)
-* [Implementing a game rule system](Implementing-a-game-rule-system.md)
-* [Inputfuncs](Inputfuncs.md)
-* [Installing on Android](Installing-on-Android.md)
-* [Internationalization](Internationalization.md)
-* [Learn Python for Evennia The Hard Way](Learn-Python-for-Evennia-The-Hard-Way.md)
-* [Licensing](Licensing.md)
-* [Links](Links.md)
-* [Locks](Locks.md)
-* [Manually Configuring Color](Manually-Configuring-Color.md)
-* [Mass and weight for objects](Mass-and-weight-for-objects.md)
-* [Messagepath](Messagepath.md)
-* [MonitorHandler](MonitorHandler.md)
-* [NPC shop Tutorial](NPC-shop-Tutorial.md)
-* [New Models](New-Models.md)
-* [Nicks](Nicks.md)
-* [OOB](OOB.md)
-* [Objects](Objects.md)
-* [Online Setup](Online-Setup.md)
-* [Parsing command arguments, theory and best practices](Parsing-command-arguments,-theory-and-best-practices.md)
-* [Portal And Server](Portal-And-Server.md)
-* [Profiling](Profiling.md)
-* [Python 3](Python-3.md)
-* [Python basic introduction](Python-basic-introduction.md)
-* [Python basic tutorial part two](Python-basic-tutorial-part-two.md)
-* [Quirks](Quirks.md)
-* [RSS](RSS.md)
-* [Roadmap](Roadmap.md)
-* [Running Evennia in Docker](Running-Evennia-in-Docker.md)
-* [Screenshot](Screenshot.md)
-* [Scripts](Scripts.md)
-* [Security](Security.md)
-* [Server Conf](Server-Conf.md)
-* [Sessions](Sessions.md)
-* [Setting up PyCharm](Setting-up-PyCharm.md)
-* [Signals](Signals.md)
-* [Soft Code](Soft-Code.md)
-* [Spawner and Prototypes](Spawner-and-Prototypes.md)
-* [Start Stop Reload](Start-Stop-Reload.md)
-* [Static In Game Map](Static-In-Game-Map.md)
-* [Tags](Tags.md)
-* [Text Encodings](Text-Encodings.md)
-* [TextTags](TextTags.md)
-* [TickerHandler](TickerHandler.md)
-* [Turn based Combat System](Turn-based-Combat-System.md)
-* [Tutorial Aggressive NPCs](Tutorial-Aggressive-NPCs.md)
-* [Tutorial NPCs listening](Tutorial-NPCs-listening.md)
-* [Tutorial Searching For Objects](Tutorial-Searching-For-Objects.md)
-* [Tutorial Tweeting Game Stats](Tutorial-Tweeting-Game-Stats.md)
-* [Tutorial Vehicles](Tutorial-Vehicles.md)
-* [Tutorial World Introduction](Tutorial-World-Introduction.md)
-* [Tutorial for basic MUSH like game](Tutorial-for-basic-MUSH-like-game.md)
-* [Tutorials](Tutorials.md)
-* [Typeclasses](Typeclasses.md)
-* [Understanding Color Tags](Understanding-Color-Tags.md)
-* [Unit Testing](Unit-Testing.md)
-* [Updating Your Game](Updating-Your-Game.md)
-* [Using MUX as a Standard](Using-MUX-as-a-Standard.md)
-* [Using Travis](Using-Travis.md)
-* [Version Control](Version-Control.md)
-* [Weather Tutorial](Weather-Tutorial.md)
-* [Web Character Generation](Web-Character-Generation.md)
-* [Web Character View Tutorial](Web-Character-View-Tutorial.md)
-* [Web Features](Web-Features.md)
-* [Web Tutorial](Web-Tutorial.md)
-* [Webclient brainstorm](Webclient-brainstorm.md)
-* [Webclient](Webclient.md)
-* [Wiki Index](Wiki-Index.md)
-* [Zones](Zones.md)
+- [A voice operated elevator using events](A-voice-operated-elevator-using-events.md)
+- [API refactoring](API-refactoring.md)
+- [Accounts](Accounts.md)
+- [Add a simple new web page](Add-a-simple-new-web-page.md)
+- [Add a wiki on your website](Add-a-wiki-on-your-website.md)
+- [Adding Command Tutorial](Adding-Command-Tutorial.md)
+- [Adding Object Typeclass Tutorial](Adding-Object-Typeclass-Tutorial.md)
+- [Administrative Docs](Administrative-Docs.md)
+- [Apache Config](Apache-Config.md)
+- [Arxcode installing help](Arxcode-installing-help.md)
+- [Async Process](Async-Process.md)
+- [Attributes](Attributes.md)
+- [Banning](Banning.md)
+- [Batch Code Processor](Batch-Code-Processor.md)
+- [Batch Command Processor](Batch-Command-Processor.md)
+- [Batch Processors](Batch-Processors.md)
+- [Bootstrap & Evennia](Bootstrap-&-Evennia.md)
+- [Bootstrap Components and Utilities](Bootstrap-Components-and-Utilities.md)
+- [Builder Docs](Builder-Docs.md)
+- [Building Permissions](Building-Permissions.md)
+- [Building Quickstart](Building-Quickstart.md)
+- [Building a mech tutorial](Building-a-mech-tutorial.md)
+- [Building menus](Building-menus.md)
+- [Choosing An SQL Server](Choosing-An-SQL-Server.md)
+- [Client Support Grid](Client-Support-Grid.md)
+- [Coding FAQ](Coding-FAQ.md)
+- [Coding Introduction](Coding-Introduction.md)
+- [Coding Utils](Coding-Utils.md)
+- [Command Cooldown](Command-Cooldown.md)
+- [Command Duration](Command-Duration.md)
+- [Command Prompt](Command-Prompt.md)
+- [Command Sets](Command-Sets.md)
+- [Command System](Command-System.md)
+- [Commands](Commands.md)
+- [Communications](Communications.md)
+- [Connection Screen](Connection-Screen.md)
+- [Continuous Integration](Continuous-Integration.md)
+- [Contributing Docs](Contributing-Docs.md)
+- [Contributing](Contributing.md)
+- [Coordinates](Coordinates.md)
+- [Custom Protocols](Custom-Protocols.md)
+- [Customize channels](Customize-channels.md)
+- [Debugging](Debugging.md)
+- [Default Command Help](Default-Command-Help.md)
+- [Default Exit Errors](Default-Exit-Errors.md)
+- [Developer Central](Developer-Central.md)
+- [Dialogues in events](Dialogues-in-events.md)
+- [Directory Overview](Directory-Overview.md)
+- [Docs refactoring](Docs-refactoring.md)
+- [Dynamic In Game Map](Dynamic-In-Game-Map.md)
+- [EvEditor](EvEditor.md)
+- [EvMenu](EvMenu.md)
+- [EvMore](EvMore.md)
+- [Evennia API](Evennia-API.md)
+- [Evennia Game Index](Evennia-Game-Index.md)
+- [Evennia Introduction](Evennia-Introduction.md)
+- [Evennia for Diku Users](Evennia-for-Diku-Users.md)
+- [Evennia for MUSH Users](Evennia-for-MUSH-Users.md)
+- [Evennia for roleplaying sessions](Evennia-for-roleplaying-sessions.md)
+- [Execute Python Code](Execute-Python-Code.md)
+- [First Steps Coding](First-Steps-Coding.md)
+- [Game Planning](Game-Planning.md)
+- [Gametime Tutorial](Gametime-Tutorial.md)
+- [Getting Started](Getting-Started.md)
+- [Glossary](Glossary.md)
+- [Grapevine](Grapevine.md)
+- [Guest Logins](Guest-Logins.md)
+- [HAProxy Config (Optional)](HAProxy-Config-(Optional).md)
+- [Help System Tutorial](Help-System-Tutorial.md)
+- [Help System](Help-System.md)
+- [How To Get And Give Help](How-To-Get-And-Give-Help.md)
+- [How to connect Evennia to Twitter](How-to-connect-Evennia-to-Twitter.md)
+- [IRC](IRC.md)
+- [Implementing a game rule system](Implementing-a-game-rule-system.md)
+- [Inputfuncs](Inputfuncs.md)
+- [Installing on Android](Installing-on-Android.md)
+- [Internationalization](Internationalization.md)
+- [Learn Python for Evennia The Hard Way](Learn-Python-for-Evennia-The-Hard-Way.md)
+- [Licensing](Licensing.md)
+- [Links](Links.md)
+- [Locks](Locks.md)
+- [Manually Configuring Color](Manually-Configuring-Color.md)
+- [Mass and weight for objects](Mass-and-weight-for-objects.md)
+- [Messagepath](Messagepath.md)
+- [MonitorHandler](MonitorHandler.md)
+- [NPC shop Tutorial](NPC-shop-Tutorial.md)
+- [New Models](New-Models.md)
+- [Nicks](Nicks.md)
+- [OOB](OOB.md)
+- [Objects](Objects.md)
+- [Online Setup](Online-Setup.md)
+- [Parsing command arguments, theory and best practices](Parsing-command-arguments,-theory-and-best-practices.md)
+- [Portal And Server](Portal-And-Server.md)
+- [Profiling](Profiling.md)
+- [Python 3](Python-3.md)
+- [Python basic introduction](Python-basic-introduction.md)
+- [Python basic tutorial part two](Python-basic-tutorial-part-two.md)
+- [Quirks](Quirks.md)
+- [RSS](RSS.md)
+- [Roadmap](Roadmap.md)
+- [Running Evennia in Docker](Running-Evennia-in-Docker.md)
+- [Screenshot](Screenshot.md)
+- [Scripts](Scripts.md)
+- [Security](Security.md)
+- [Server Conf](Server-Conf.md)
+- [Sessions](Sessions.md)
+- [Setting up PyCharm](Setting-up-PyCharm.md)
+- [Signals](Signals.md)
+- [Soft Code](Soft-Code.md)
+- [Spawner and Prototypes](Spawner-and-Prototypes.md)
+- [Start Stop Reload](Start-Stop-Reload.md)
+- [Static In Game Map](Static-In-Game-Map.md)
+- [Tags](Tags.md)
+- [Text Encodings](Text-Encodings.md)
+- [TextTags](TextTags.md)
+- [TickerHandler](TickerHandler.md)
+- [Turn based Combat System](Turn-based-Combat-System.md)
+- [Tutorial Aggressive NPCs](Tutorial-Aggressive-NPCs.md)
+- [Tutorial NPCs listening](Tutorial-NPCs-listening.md)
+- [Tutorial Searching For Objects](Tutorial-Searching-For-Objects.md)
+- [Tutorial Tweeting Game Stats](Tutorial-Tweeting-Game-Stats.md)
+- [Tutorial Vehicles](Tutorial-Vehicles.md)
+- [Tutorial World Introduction](Tutorial-World-Introduction.md)
+- [Tutorial for basic MUSH like game](Tutorial-for-basic-MUSH-like-game.md)
+- [Tutorials](Tutorials.md)
+- [Typeclasses](Typeclasses.md)
+- [Understanding Color Tags](Understanding-Color-Tags.md)
+- [Unit Testing](Unit-Testing.md)
+- [Updating Your Game](Updating-Your-Game.md)
+- [Using MUX as a Standard](Using-MUX-as-a-Standard.md)
+- [Using Travis](Using-Travis.md)
+- [Version Control](Version-Control.md)
+- [Weather Tutorial](Weather-Tutorial.md)
+- [Web Character Generation](Web-Character-Generation.md)
+- [Web Character View Tutorial](Web-Character-View-Tutorial.md)
+- [Web Features](Web-Features.md)
+- [Web Tutorial](Web-Tutorial.md)
+- [Webclient brainstorm](Webclient-brainstorm.md)
+- [Webclient](Webclient.md)
+- [Wiki Index](Wiki-Index.md)
+- [Zones](Zones.md)
+- [index](index.md)
\ No newline at end of file