Some more refactoring

docs/source/Contributing-Docs.md

@@ -1,47 +1,45 @@
-# Evennia docs
+# Contributing to 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 
+Contributing to the docs is is like [contributing to the rest of Evennia][contributing]:
-[https://evennia.github.io/evennia/latest](https://evennia.github.io/evennia/latest).
+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!
-## 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
+> Note: Don't edit the files in `evennia/docs/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 sources in `evennia/docs/source/` are built into a documentation using the
-the [Sphinx][sphinx] static generator system. To do so locally you need to either
+[Sphinx][sphinx] static generator system. To do this locally you need to use a
-use a system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking that, you could
+system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking
-in principle also run the sphinx build-commands manually - read the `evennia/docs/Makefile` to see 
+that, you could in principle also run the sphinx build-commands manually - read
-which commands are run by `make`.
+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.  But
+You don't necessarily _have_ to build the docs locally to contribute. Markdown is
-building them allows you to check for yourself that syntax is correct and that
+not hard and is very readable on its raw text-form.
-your change comes out looking as you expected.
+
+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 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
 
-If you only want to build the main documentation pages (not the API auto-docs),
+This is the fastest way to compile and view your changes. It will only build
-you don't need to install Evennia itself, only the documentation resources.
+the main documentation pages and not the API auto-docs or versions.  All is
-All is done in your terminal/console.
+done in your terminal/console.
 
 - (Optional, but recommended): Activate a virtualenv with Python 3.7.
 - `cd` to into the `evennia/docs` folder.
@@ -53,14 +51,14 @@ All is done in your terminal/console.
     pip install -r requirements.txt
     ```
 
-- Next, build the html-based documentation:
+- 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/`. Note any errors from files you have edited.
+  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!
@@ -580,7 +578,7 @@ for more flexibility. It also provides a link to the code block, identified by i
 
 ```code-block:: python
     :linenos:
-    :emphasize-lines: 6-7,12
+    :emphasize-lines: 1-2,8
     :caption: An example code block
     :name: A full code block example
 
@@ -626,3 +624,6 @@ to understand our friendly Google-style docstrings used in classes and functions
 [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/

docs/source/_static/nature.css

@@ -16,7 +16,7 @@
 body {
     font-family: Arial, sans-serif;
     font-size: 100%;
-    background-color: #fff;
+    background-color: #eee;
     color: #555;
     margin: 0;
     padding: 0;
@@ -29,7 +29,6 @@ div.documentwrapper {
 
 div.bodywrapper {
     margin: 0 0 0 230px;
-    height: 88vh;
 }
 
 hr {
@@ -46,7 +45,6 @@ div.body {
     padding: 0 30px 30px 30px;
     font-size: 0.9em;
     margin-top: -9px;
-    height: 85vh;
 }
 
 div.footer {
@@ -198,15 +196,14 @@ div.body h6 {
 }
 
 a.headerlink {
-    color: #cfdde8;
+    color: #7caeb7;
     font-size: 0.8em;
     padding: 0 4px 0 4px;
     text-decoration: none;
 }
 
 a.headerlink:hover {
-    /*! background-color: #c60f0f; */
+    color: #7caeb7;
-    color: #9bced7;
 }
 
 div.body p, div.body dd, div.body li {