Experimenting with variations in recommonmark

docs/source/conf.py

@@ -117,9 +117,9 @@ autodoc_default_options = {
     "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
@@ -128,6 +128,7 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
     return False
 
 
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -148,25 +149,28 @@ smv_outputdir_format = "versions" + sep + "{config.release}"
 _github_code_root = "https://github.com/evennia/tree/master/"
 _github_doc_root = "https://github.com/evennia/tree/master/docs/sources/"
 
+# recommonmark
 
 def url_resolver(url):
     if url.startswith("github:"):
         return _github_code_root + url[7:]
+    elif url.startswith("api:"):
+        return f"api/{url[4:]}.rst"
     else:
         return _github_doc_root + url
 
-
-# dynamic setup
-
 auto_toc_sections = ["Contents", "Toc", "Index"]
 
+recommonmark_config = {
+    "enable_auto_doc_ref": True,
+    "enable_auto_toc_tree": True,
+    "url_resolver": url_resolver,
+    "auto_toc_tree_section": ["Contents", "Toc", "Index"],
+}
+
 
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member)
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': url_resolver,
-            'auto_toc_tree_section': auto_toc_sections,
-            }, True)
     app.add_transform(AutoStructify)
 
     # custom lunr-based search

docs/source/index.md

@@ -15,12 +15,12 @@ There is [a lengthier introduction](Evennia-Introduction) to read. You might als
 |-----------------|----------------------|--------------------------|----------------------|----------------------------|--------------------|
 |[Getting Started](Getting-Started)| [Admin Docs](Administrative-Docs) | [Builder Docs](Builder-Docs) | [Developer Central](Developer-Central) | [Tutorials & Examples](Tutorials) | [API](evennia) |
 
-- The [Getting Started](Getting-Started) page helps installing and starting Evennia for the first time.
+- [Getting Started](Getting-Started) page helps installing and starting Evennia for the first time.
-- The [Admin Docs](Administrative-Docs) covers running and maintaining an Evennia server.
+- [Admin Docs](Administrative-Docs) covers running and maintaining an Evennia server.
-- The [Builder Docs](Builder-Docs) helps for starting to build a game world using Evennia.
+- [Builder Docs](Builder-Docs) helps for starting to build a game world using Evennia.
-- The [Developer Central](Developer-Central) describes how Evennia works and is used by coders.
+- [Developer Central](Developer-Central) describes how Evennia works and is used by coders.
-- The [Tutorials & Examples](Tutorials) contains help pages on a step-by-step or tutorial format.
+- [Tutorials & Examples](Tutorials) contains help pages on a step-by-step or tutorial format.
-- The [API](evennia) documentation is created from the latest source code.
+- [API](api:evennia) documentation is created from the latest source code.
 
 [search]: https://www.google.com/cse/publicurl?cx=010440404980795145992:6ztkvqc46je
 [group]: https://groups.google.com/forum/#%21forum/evennia

docs/source/toc.md

@@ -1,5 +1,6 @@
 # Toc
 
+* [index](index.md)
 * [A voice operated elevator using events](A-voice-operated-elevator-using-events.md)
 * [API refactoring](API-refactoring.md)
 * [Accounts](Accounts.md)