Cleaned up doc config file

docs/source/conf.py

@@ -6,55 +6,24 @@
 
 import os
 import sys
-from os.path import sep
+import sphinx_theme
 from recommonmark.transform import AutoStructify
 from sphinx.util.osutil import cd
 
 
-_no_autodoc = os.environ.get("NOAUTODOC")
-
-if not _no_autodoc:
-    # we must set up Evennia and its paths for autodocs to work
-
-    EV_ROOT = os.environ.get("EVDIR")
-    GAME_DIR = os.environ.get("EVGAMEDIR")
-
-    if not (EV_ROOT and GAME_DIR):
-        err = ("The EVDIR and EVGAMEDIR environment variables must be set to "
-              "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))
-
-    sys.path.insert(1, EV_ROOT)
-    sys.path.insert(1, GAME_DIR)
-
-    with cd(GAME_DIR):
-        # set up Evennia so its sources can be parsed
-        os.environ["DJANGO_SETTINGS_MODULE"] = "server.conf.settings"
-
-        import django  # noqa
-        django.setup()
-
-        import evennia  # noqa
-        evennia._init()
-
-
 # -- Project information -----------------------------------------------------
 
-project = 'Evennia'
+project = "Evennia"
-copyright = '2020, The Evennia developer community'
+copyright = "2020, The Evennia developer community"
-author = '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 = "1.0-dev"
 
-# The full version, including alpha/beta/rc tags
-release = '1.0-dev'
 
 # -- 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",
@@ -62,21 +31,40 @@ extensions = [
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.viewcode",
     # "sphinxcontrib.lunrsearch",
+    "sphinx.ext.todo",
+    "sphinx.ext.githubpages",
 ]
 
 # 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']
+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']
+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 = "standford_theme"
+# html_theme_path = [sphinx_theme.get_html_theme_path("stanford_theme")]
 
 # Custom extras for sidebar
 html_sidebars = {
-    '**': [
+    "**": [
         "searchbox.html",
         "localtoc.html",
         # "globaltoc.html",
@@ -87,67 +75,12 @@ html_sidebars = {
 }
 html_favicon = "_static/favicon.ico"
 
-
+# HTML syntax highlighting style
-# napoleon Google-style docstring parser
+pygments_style = "sphinx"
-
-napoleon_google_docstring = True
-napoleon_numpy_docstring = False
-napoleon_include_init_with_doc = False
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = False
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_keyword = True
-napoleon_use_rtype = True
 
 
-# settings for sphinxcontrib.apidoc to auto-run sphinx-apidocs
+# -- Recommonmark ------------------------------------------------------------
-
+# allows for writing Markdown and convert to rst dynamically
-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
 
@@ -164,10 +97,10 @@ def url_resolver(url):
     if url.lower().strip() in choose_issue:
         return _github_issue_choose
     elif url.startswith(urlstart):
-        return _github_code_root + url[len(urlstart):]
+        return _github_code_root + url[len(urlstart) :]
     elif url.startswith(apistart):
         print("api: -> api ref")
-        return "api/" + url[len(apistart):] + ".html"
+        return "api/" + url[len(apistart) :] + ".html"
     return url
     # else:
     #     return _github_doc_root + url
@@ -180,11 +113,88 @@ recommonmark_config = {
     "enable_auto_toc_tree": True,
     "url_resolver": url_resolver,
     "auto_toc_tree_section": ["Contents", "Toc", "Index"],
-    "code_highlight_options": {"force": True,
+    "code_highlight_options": {"force": True, "linenos": 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:
+    # we must set up Evennia and its paths for autodocs to work
+
+    EV_ROOT = os.environ.get("EVDIR")
+    GAME_DIR = os.environ.get("EVGAMEDIR")
+
+    if not (EV_ROOT and GAME_DIR):
+        err = (
+            "The EVDIR and EVGAMEDIR environment variables must be set to "
+            "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))
+
+    sys.path.insert(1, EV_ROOT)
+    sys.path.insert(1, GAME_DIR)
+
+    with cd(GAME_DIR):
+        # set up Evennia so its sources can be parsed
+        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"]
+
+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
+
+
+# Napoleon Google-style docstring parser for autodocs
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_keyword = True
+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)

docs/source/index.md

@@ -11,11 +11,8 @@
 
 # Evennia Documentation
 
-This is the manual of [Evennia](http://www.evennia.com), the open source Python `MU*` creation system.
+This is the manual of [Evennia](http://www.evennia.com), the open source Python
-You can [Search][search] the documentation as well as browse all pages alphabetically in the
+`MU*` creation system.
-[Index](Wiki-Index). If you have trouble with unclear documentation, please let us know on our
-[mailing list][group], over [IRC][chat] or by dropping a note in our quick no-registration [online
-suggestion box][form]!
 
 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).