Back-port some config/readme from develop

docs/README.md

@@ -1,4 +1,5 @@
-# evennia-docs
+# Evennia docs
+
 Documentation for the Evennia MUD creation system.
 
 > WARNING: This system is still WIP and many things are bound to change!
@@ -9,26 +10,25 @@ The live documentation is (will in the future be) available at `https://evennia.
 # 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 use
+Markdown files are simple text files that can be edited with a normal text editor. They primaroly use
-the [Markdown][commonmark] syntax.
+the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help.
 
 Don't edit the files in `source/api/`. These are auto-generated and your changes
 will be lost.
 
-See also later in this doc for [Help with editing syntax](#Help-with-editing-syntax).
-
 ## Contributing
 
 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 and make a PR for it!
+own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it!
 
-# Building the docs
+# 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/Windows-WSL) or run sphinx-commands manually
+use a system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking that, you could
-(read the `Makefile` to see which commands are run by `make`).
+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
@@ -159,72 +159,316 @@ can now deploy.
 - After deployment finishes, the updated live documentation will be
 available at `https://evennia.github.io/evennia/`.
 
-# Help with editing syntax
+# Editing syntax
 
-> This needs expanding in the future.
+The format 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.
 
-## Referring to a heading in the same file
+## Italic/Bold 
 
-You can self-reference by pointing to a header/label elsewhere in the
+We generally use underscores for italics and double-asterisks for bold:
-same document by using `#` and replacing any spaces in the name with `-`.
+
+- `_Italic 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` 
+
+> 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:
+
+```markdown
+- first bulletpoint
+- second bulletpoint
+- third bulletpoint
+```
+```markdown
+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 `>`.
 
 ```
-This is a [link to the heading](#My-Heading-Name).
+> Note: This is an important 
+> thing to remember.  
+```
 
-# My Heading Name
+## Links 
+
+- `[linktext](url_or_ref)` - gives a clickable link `linktext`. 
+
+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
 
 ```
 
-## Referring to titles in another file
+### Special references 
 
-> WIP: Most of these special structures need more work and checking.
+The Evennia documentation supports some special reference shortcuts in links:
 
-If file1 looks like this:
+#### 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): 
 
 ```
-# Header title
+This is normal text 
 
+    This is verbatim text 
+
+This is normal text 
 ```
 
-You can refer to it from another file as
+Another way is to use triple-backticks:
+
+````
+```
+Everything within these backticks will be verbatim.
 
 ```
-Read more about it [here](path.to.file1.md:Header title)
+````
 
+## 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 
+    
+``` 
+````
+
+## 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. 
 
 ```
-> This is not actually working at this time (WIP)
+````
+There is also a short-hand form for starting a [ReST directive][ReST-directives] without need for `eval_rst`:
 
-To refer to code in the Evennia repository, you can use a relative reference from the docs/ folder:
+````
+```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.
 ```
-You can find this code [here](../evennia/objects/objects.py).
+````
 
+See below for examples of this.
+
+#### Important
+
+This will display a one-line note that will pop even more than a normal `> note`.
+
+````
+```important:: 
+  This is important because it is!
 ```
-This will be automatically translated to the matching github link so the reader can click and jump to that code directly.
+````
-> This is not currently working. (WIP)
 
+#### Warning
 
-## Making toc-tree indices
+A warning block is used to draw attention to particularly dangerous things, or features easy to 
+mess up.
 
-To make a Table-of-Contents listing (what Sphinx refers to as a "Toc Tree"), one
+````
-must make new heading named either `Contents` or `Index`, followed by a bullet-list of
+```warning::
-links:
+  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
 ```
-# Index
+````
-
-- [Title1](doc1)
-- [Title2](doc2)
 
+````
+```versionchanged:: 1.0
+  How the feature changed with this version.
 ```
-
+````
-This will create a toc-tree structure behind the scenes.
+````
+```deprecated:: 1.0
+```
+````
 
 
+#### Sidebar 
 
-We may expand on this later. For now, check out existing docs and refer to the
+This will display an informative sidebar that floats to the side of regular content. This is useful
-[Markdown][commonmark] (CommonMark) specification.
+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.
+```
+````
+
+> 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. 
+
+#### 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
+=====  =====  =======
+```
+````
+
+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             | ...        | ...      |          |
++------------------------+------------+----------+----------+
+```
+````
+
+#### 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())
+```
+````
+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
 
@@ -237,11 +481,16 @@ For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon
 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]: https://github.com/evennia/evennia/wiki/Getting-Started
 [contributing]: https://github.com/evennia/evennia/wiki/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

docs/source/conf.py

@@ -6,11 +6,149 @@
 
 import os
 import sys
-from os.path import sep
+import sphinx_theme
 from recommonmark.transform import AutoStructify
 from sphinx.util.osutil import cd
 
 
+# -- Project information -----------------------------------------------------
+
+project = "Evennia"
+copyright = "2020, The Evennia developer community"
+author = "The Evennia developer community"
+
+# The full Evennia version covered by these docs, including alpha/beta/rc tags
+# This will be used for multi-version selection options.
+release = "0.9.1"
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "recommonmark",
+    "sphinx_multiversion",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.viewcode",
+    # "sphinxcontrib.lunrsearch",
+    "sphinx.ext.todo",
+    "sphinx.ext.githubpages",
+]
+
+source_suffix = ['.md', '.rst']
+master_doc = 'index'
+
+# make sure sectionlabel references can be used as path/to/file:heading
+autosectionlabel_prefix_document = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+
+# -- Sphinx-multiversion config ----------------------------------------------
+
+# which branches to include in multi-versioned docs
+# - master, develop and vX.X branches
+smv_branch_whitelist = r"^master$|^develop$|^v[0-9\.]+?$"
+smv_outputdir_format = "{config.release}"
+# don't make docs for tags
+smv_tag_whitelist = r"^$"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# html_theme = "alabaster"
+html_theme = "stanford_theme"
+html_theme_path = [sphinx_theme.get_html_theme_path("stanford_theme")]
+
+# Custom extras for sidebar
+html_sidebars = {
+    "**": [
+        "searchbox.html",
+        "localtoc.html",
+        # "globaltoc.html",
+        "relations.html",
+        "sourcelink.html",
+        "versioning.html",
+    ]
+}
+html_favicon = "_static/favicon.ico"
+
+# HTML syntax highlighting style
+pygments_style = "sphinx"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+# experimental, not working well atm
+
+latex_engine = 'xelatex'
+latex_show_urls = 'footnote'
+latex_elements = {
+    'papersize': 'a4paper',
+    'fncychap': r'\usepackage[Bjarne]{fncychap}',
+    'fontpkg': r'\usepackage{times,amsmath,amsfonts,amssymb,amsthm}',
+    'preamble': r'''
+        \usepackage[utf8]{fontenc}
+        \usepackage{amsmath,amsfonts,amssymb,amsthm}
+        \usepackage[math-style=literal]{unicode-math}
+        \usepackage{newunicodechar}
+        \usepackage{graphicx}
+    '''
+}
+latex_documents = [
+    (master_doc,  'main.tex', 'Sphinx format', 'Evennia', 'report'),
+    ("toc", 'toc.tex', 'TOC', 'Evennia', 'report')
+]
+
+
+# -- Recommonmark ------------------------------------------------------------
+# allows for writing Markdown and convert to rst dynamically
+
+# reroute to github links or to the api
+
+_github_code_root = "https://github.com/evennia/evennia/blob/"
+_github_doc_root = "https://github.com/evennia/tree/master/docs/sources/"
+_github_issue_choose = "https://github.com/evennia/evennia/issues/new/choose"
+
+
+def url_resolver(url):
+    githubstart = "github:"
+    apistart = "api:"
+    choose_issue = ("feature-request", "report-bug", "issue", "bug-report")
+
+    if url.lower().strip() in choose_issue:
+        return _github_issue_choose
+
+    elif url.startswith(githubstart):
+        urlpath = url[len(githubstart):]
+        if not (urlpath.startswith("develop/") or urlpath.startswith("master")):
+            urlpath = "master/" + urlpath 
+        return _github_code_root + urlpath
+    elif url.startswith(apistart):
+        return "api/" + url[len(apistart) :] + ".html"
+    return url
+    # else:
+    #     return _github_doc_root + url
+
+
+# auto-create TOCs if a list of links is under these headers
+auto_toc_sections = ["Contents", "Toc", "Index"]
+
+recommonmark_config = {
+    "enable_auto_toc_tree": True,
+    "url_resolver": url_resolver,
+    "auto_toc_tree_section": ["Contents", "Toc", "Index"],
+    "code_highlight_options": {"force": True, "linenos": True},
+}
+
+
+# -- API/Autodoc ---------------------------------------------------------------
+# automatic creation of API documentation. This requires a valid Evennia setup
+
 _no_autodoc = os.environ.get("NOAUTODOC")
 
 if not _no_autodoc:
@@ -20,9 +158,11 @@ if not _no_autodoc:
     GAME_DIR = os.environ.get("EVGAMEDIR")
 
     if not (EV_ROOT and GAME_DIR):
-        err = ("The EVDIR and EVGAMEDIR environment variables must be set to "
+        err = (
-              "the absolute paths to the evennia/ repo and an initialized "
+            "The EVDIR and EVGAMEDIR environment variables must be set to "
-              "evennia gamedir respectively.")
+            "the absolute paths to the evennia/ repo and an initialized "
+            "evennia gamedir respectively."
+        )
         raise RuntimeError(err)
 
     print("Evennia root: {}, Game dir: {}".format(EV_ROOT, GAME_DIR))
@@ -35,60 +175,36 @@ if not _no_autodoc:
         os.environ["DJANGO_SETTINGS_MODULE"] = "server.conf.settings"
 
         import django  # noqa
+
         django.setup()
 
         import evennia  # noqa
+
         evennia._init()
 
+if _no_autodoc:
+    exclude_patterns = ["api/*"]
+else:
+    exclude_patterns = ["api/*migrations.rst"]
 
-# -- Project information -----------------------------------------------------
+autodoc_default_options = {
-
+    "members": True,
-project = 'Evennia'
+    "undoc-members": True,
-copyright = '2020, The Evennia developer community'
+    "show-inheritance": True,
-author = 'The Evennia developer community'
+    "special-members": "__init__",
-
+    "enable_eval_rst": True,
-# The full version, including alpha/beta/rc tags
-release = '0.9.1'
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "recommonmark",
-    "sphinx_multiversion",
-    "sphinx.ext.napoleon",
-    "sphinx.ext.autosectionlabel",
-    "sphinx.ext.viewcode",
-    # "sphinxcontrib.lunrsearch",
-]
-
-# make sure sectionlabel references can be used as path/to/file:heading
-autosectionlabel_prefix_document = True
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# Custom extras for sidebar
-html_sidebars = {
-    '**': [
-        "searchbox.html",
-        "localtoc.html",
-        # "globaltoc.html",
-        "relations.html",
-        "sourcelink.html",
-        "versioning.html",
-    ]
 }
-html_favicon = "_static/favicon.ico"
 
 
-# napoleon Google-style docstring parser
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    if _no_autodoc:
+        return True
+    if name.startswith("__") and name != "__init__":
+        return True
+    return False
+
+
+# Napoleon Google-style docstring parser for autodocs
 
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False
@@ -104,85 +220,8 @@ napoleon_use_keyword = True
 napoleon_use_rtype = True
 
 
-# settings for sphinxcontrib.apidoc to auto-run sphinx-apidocs
+# -- Main config setup ------------------------------------------
-
+# last setup steps for some plugins
-if _no_autodoc:
-    exclude_patterns = ["api/*"]
-else:
-    exclude_patterns = ["api/*migrations.rst"]
-
-# for inline autodoc
-
-autodoc_default_options = {
-    "members": True,
-    "undoc-members": True,
-    "show-inheritance": True,
-    "special-members": "__init__",
-    "enable_eval_rst": True,
-}
-
-def autodoc_skip_member(app, what, name, obj, skip, options):
-    if _no_autodoc:
-        return True
-    if name.startswith("__") and name != "__init__":
-        return True
-    return False
-
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'alabaster'
-
-
-# sphinx-multiversion config
-
-smv_tag_whitelist = r"^$"
-# which branches to include in multi-version docs
-# - master, develop and vX.X branches
-smv_branch_whitelist = r"^master$|^develop$|^v[0-9\.]+?$"
-smv_outputdir_format = "{config.release}"
-
-
-# recommonmark
-
-# reroute to github links or to the api
-
-_github_code_root = "https://github.com/evennia/evennia/blob/master/"
-_github_doc_root = "https://github.com/evennia/tree/master/docs/sources/"
-_github_issue_choose = "https://github.com/evennia/evennia/issues/new/choose"
-
-
-def url_resolver(url):
-    urlstart = "github:"
-    apistart = "api:"
-    choose_issue = ("feature-request", "report-bug", "issue")
-
-    if url.lower().strip() in choose_issue:
-        return _github_issue_choose
-    elif url.startswith(urlstart):
-        return _github_code_root + url[len(urlstart):]
-    elif url.startswith(apistart):
-        print("api: -> api ref")
-        return "api/" + url[len(apistart):] + ".html"
-    return url
-    # else:
-    #     return _github_doc_root + url
-
-
-# auto-create TOCs if a list of links is under these headers
-auto_toc_sections = ["Contents", "Toc", "Index"]
-
-recommonmark_config = {
-    "enable_auto_toc_tree": True,
-    "url_resolver": url_resolver,
-    "auto_toc_tree_section": ["Contents", "Toc", "Index"],
-    "code_highlight_options": {"force": True,
-                               "linenos": True}
-}
 
 
 def setup(app):