From e930bd4ff13fb3b53541523ce84c28524516fd64 Mon Sep 17 00:00:00 2001
From: Griatch <griatch@gmail.com>
Date: Sat, 14 Nov 2020 11:53:15 +0100
Subject: [PATCH] Fix doc header for better build

---
 docs/source/Setup/Setup-Quickstart.md |  5 +++
 docs/source/index.md                  | 14 +++---
 docs/source/toc.md                    |  2 +-
 evennia/utils/ansi.py                 | 61 +++++++++++++++++++++++----
 4 files changed, 66 insertions(+), 16 deletions(-)

diff --git a/docs/source/Setup/Setup-Quickstart.md b/docs/source/Setup/Setup-Quickstart.md
index 5920a0920d..75df89acfc 100644
--- a/docs/source/Setup/Setup-Quickstart.md
+++ b/docs/source/Setup/Setup-Quickstart.md
@@ -11,6 +11,11 @@ Evennia requires Python3.7+. As with most Python packages, using a
 installation independent from the system libraries. It's _not_ recommended 
 to install Evennia as superuser. 
 
+```warning::
+
+   This is not yet available. Switch to the 0.9.5 version of these docs to install Evennia.
+```
+
     pip install evennia
 
 Make sure the `evennia` command works. Use `evennia -h` for usage help (or read on).
diff --git a/docs/source/index.md b/docs/source/index.md
index 2a22d053bd..c1f14b6847 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,14 +1,14 @@
 
 ```warning::
 
-  This is the **experimental** and **unstable** documentation for the
-  development branch of Evennia (v1.0-dev). It's based on converted docs
-  from the Evennia wiki (https://github.com/evennia/evennia/wiki/) at
-  2020-06-12 22:36:53. There are known conversion issues and missing links.
-  This will slowly be ironed out as this is developed.
+  This is the **WIP** documentation for the
+  development branch of Evennia (v1.0-dev). The text is based on the 
+  original Evennia `wiki <https://github.com.evennia/evennia/wiki>`_ 
+  but it's being refactored heavily. There are known conversion issues 
+  and missing links. This will slowly be ironed out as this is developed.
 
-  For now you are best off using the original wiki, or the less changing v0.9.5
-  of these docs. You have been warned.
+  New things will be added to this version only, but for now you are best 
+  off using v0.9.5 of the docs, or the original wiki. You have been warned.
 ```
 
 # Evennia Documentation
diff --git a/docs/source/toc.md b/docs/source/toc.md
index de2c0a32b3..21f7217eee 100644
--- a/docs/source/toc.md
+++ b/docs/source/toc.md
@@ -1,5 +1,5 @@
 # Toc
-
+- [API root](api/evennia-api.rst)
 - [Coding/Coding Introduction](Coding/Coding-Introduction)
 - [Coding/Coding Overview](Coding/Coding-Overview)
 - [Coding/Continuous Integration](Coding/Continuous-Integration)
diff --git a/evennia/utils/ansi.py b/evennia/utils/ansi.py
index e954590fbb..1924cfd771 100644
--- a/evennia/utils/ansi.py
+++ b/evennia/utils/ansi.py
@@ -1,19 +1,64 @@
 """
 ANSI - Gives colour to text.
 
-Use the codes defined in ANSIPARSER in your text
-to apply colour to text according to the ANSI standard.
+Use the codes defined in the *ANSIParser* class to apply colour to text. The
+`parse_ansi` function in this module parses text for markup and `strip_ansi`
+removes it.
 
-Examples:
+You should usually not need to call `parse_ansi` explicitly; it is run by
+Evennia just before returning data to/from the user. Alternative markup is
+possible by overriding the parser class (see also contrib/ for deprecated
+markup schemes).
+
+
+Supported standards:
+
+- ANSI 8 bright and 8 dark fg (foreground) colors
+- ANSI 8 dark bg (background) colors
+- 'ANSI' 8 bright bg colors 'faked' with xterm256 (bright bg not included in ANSI standard)
+- Xterm256 - 255 fg/bg colors + 26 greyscale fg/bg colors
+
+## Markup
+
+ANSI colors: `r` ed, `g` reen, `y` ellow, `b` lue, `m` agenta, `c` yan, `n` ormal (no color). Capital
+letters indicate the 'dark' variant.
+
+- `|r` fg bright red
+- `|R` fg dark red
+- `|[r` bg bright red
+- `|[R` bg dark red
+- `|[R|g` bg dark red, fg bright green
 
 ```python
 "This is |rRed text|n and this is normal again."
+
 ```
 
-Mostly you should not need to call `parse_ansi()` explicitly;
-it is run by Evennia just before returning data to/from the
-user.  Depreciated example forms are available by extending
-the ansi mapping.
+Xterm256 colors are given as RGB (Red-Green-Blue), with values 0-5:
+
+- `|500` fg bright red
+- `|050` fg bright green
+- `|005` fg bright blue
+- `|110` fg dark brown
+- `|425` fg pink
+- `|[431` bg orange
+
+Xterm256 greyscale:
+
+- `|=a` fg black
+- `|=g` fg dark grey
+- `|=o` fg middle grey
+- `|=v` fg bright grey
+- `|=z` fg white
+- `|[=r` bg middle grey
+
+```python
+"This is |500Red text|n and this is normal again."
+"This is |[=jText on dark grey background"
+
+```
+
+----
 
 """
 import functools
@@ -85,7 +130,7 @@ class ANSIParser(object):
     to ANSI command sequences
 
     We also allow to escape colour codes
-    by prepending with an extra |.
+    by prepending with an extra `|`.
 
     """