From 30ac8a6103bd185bca4e47fbe9a64a8ae93978ff Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 14 Jun 2020 11:45:10 +0200 Subject: [PATCH] Cleaned up doc config file --- docs/source/conf.py | 220 ++++++++++++++++++++++--------------------- docs/source/index.md | 7 +- 2 files changed, 117 insertions(+), 110 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 627f62c2db..d56403b4cc 100644 --- a/docs/source/conf.py +++ b/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' -copyright = '2020, The Evennia developer community' -author = 'The Evennia developer community' +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 = "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" - -# napoleon Google-style docstring parser - -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 +# HTML syntax highlighting style +pygments_style = "sphinx" -# settings for sphinxcontrib.apidoc to auto-run sphinx-apidocs - -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 +# -- Recommonmark ------------------------------------------------------------ +# allows for writing Markdown and convert to rst dynamically # 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, - "linenos": True} + "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: + # 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) diff --git a/docs/source/index.md b/docs/source/index.md index 7f1206224c..1f9823b5a2 100644 --- a/docs/source/index.md +++ b/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. -You can [Search][search] the documentation as well as browse all pages alphabetically in the -[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]! +This is the manual of [Evennia](http://www.evennia.com), the open source Python +`MU*` creation system. 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).