mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
Copy doc tools from develop
This commit is contained in:
Griatch
parent
ca97c9bda0
commit
c52f505d00
127 changed files with 2927 additions and 1427 deletions
|
|
@ -6,6 +6,7 @@
|
|||
|
||||
import os
|
||||
import sys
|
||||
import re
|
||||
import sphinx_theme
|
||||
from recommonmark.transform import AutoStructify
|
||||
from sphinx.util.osutil import cd
|
||||
|
|
@ -35,8 +36,8 @@ extensions = [
|
|||
"sphinx.ext.githubpages",
|
||||
]
|
||||
|
||||
source_suffix = ['.md', '.rst']
|
||||
master_doc = 'index'
|
||||
source_suffix = [".md", ".rst"]
|
||||
master_doc = "index"
|
||||
|
||||
# make sure sectionlabel references can be used as path/to/file:heading
|
||||
autosectionlabel_prefix_document = True
|
||||
|
|
@ -61,9 +62,7 @@ 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")]
|
||||
html_theme = "nature"
|
||||
|
||||
# Custom extras for sidebar
|
||||
html_sidebars = {
|
||||
|
|
@ -76,7 +75,9 @@ html_sidebars = {
|
|||
"versioning.html",
|
||||
]
|
||||
}
|
||||
html_favicon = "_static/favicon.ico"
|
||||
html_favicon = "_static/images/favicon.ico"
|
||||
html_logo = "_static/images/evennia_logo.png"
|
||||
html_short_title = f"Evennia {release}"
|
||||
|
||||
# HTML syntax highlighting style
|
||||
pygments_style = "sphinx"
|
||||
|
|
@ -85,23 +86,23 @@ pygments_style = "sphinx"
|
|||
# -- Options for LaTeX output ------------------------------------------------
|
||||
# experimental, not working well atm
|
||||
|
||||
latex_engine = 'xelatex'
|
||||
latex_show_urls = 'footnote'
|
||||
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'''
|
||||
"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')
|
||||
(master_doc, "main.tex", "Sphinx format", "Evennia", "report"),
|
||||
("toc", "toc.tex", "TOC", "Evennia", "report"),
|
||||
]
|
||||
|
||||
|
||||
|
|
@ -116,31 +117,51 @@ _github_issue_choose = "https://github.com/evennia/evennia/issues/new/choose"
|
|||
|
||||
|
||||
def url_resolver(url):
|
||||
"""
|
||||
Convert urls by catching special markers.
|
||||
"""
|
||||
githubstart = "github:"
|
||||
apistart = "api:"
|
||||
choose_issue = ("feature-request", "report-bug", "issue", "bug-report")
|
||||
choose_issue = "github:issue"
|
||||
sourcestart = "src:"
|
||||
|
||||
if url.lower().strip() in choose_issue:
|
||||
if url.endswith(choose_issue):
|
||||
return _github_issue_choose
|
||||
|
||||
elif url.startswith(githubstart):
|
||||
urlpath = url[len(githubstart):]
|
||||
elif githubstart in url:
|
||||
urlpath = url[url.index(githubstart) + len(githubstart):]
|
||||
if not (urlpath.startswith("develop/") or urlpath.startswith("master")):
|
||||
urlpath = "master/" + urlpath
|
||||
urlpath = "master/" + urlpath
|
||||
return _github_code_root + urlpath
|
||||
elif url.startswith(apistart):
|
||||
return "api/" + url[len(apistart) :] + ".html"
|
||||
elif apistart in url:
|
||||
# locate the api/ folder in the doc structure
|
||||
ind = url.index(apistart)
|
||||
depth = url[:ind].count("/") + 1
|
||||
path = "../".join("" for _ in range(depth))
|
||||
urlpath = path + "api/" + url[ind + len(apistart):] + ".html"
|
||||
return urlpath
|
||||
elif sourcestart in url:
|
||||
ind = url.index(sourcestart)
|
||||
depth = url[:ind].count("/") + 1
|
||||
path = "../".join("" for _ in range(depth))
|
||||
|
||||
modpath, *inmodule = url[ind + len(sourcestart):].rsplit("#", 1)
|
||||
modpath = "/".join(modpath.split("."))
|
||||
inmodule = "#" + inmodule[0] if inmodule else ""
|
||||
modpath = modpath + ".html" + inmodule
|
||||
|
||||
urlpath = path + "_modules/" + modpath
|
||||
return urlpath
|
||||
|
||||
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"]
|
||||
auto_toc_sections = ["Contents", "Toc", "Index", "API", "Overview"]
|
||||
|
||||
recommonmark_config = {
|
||||
"enable_auto_toc_tree": True,
|
||||
"url_resolver": url_resolver,
|
||||
"auto_toc_maxdepth": 1,
|
||||
"auto_toc_tree_section": ["Contents", "Toc", "Index"],
|
||||
"code_highlight_options": {"force": True, "linenos": True},
|
||||
}
|
||||
|
|
@ -151,6 +172,8 @@ recommonmark_config = {
|
|||
|
||||
_no_autodoc = os.environ.get("NOAUTODOC")
|
||||
|
||||
ansi_clean = None
|
||||
|
||||
if not _no_autodoc:
|
||||
# we must set up Evennia and its paths for autodocs to work
|
||||
|
||||
|
|
@ -182,6 +205,9 @@ if not _no_autodoc:
|
|||
|
||||
evennia._init()
|
||||
|
||||
from evennia.utils.ansi import strip_raw_ansi as ansi_clean
|
||||
|
||||
|
||||
if _no_autodoc:
|
||||
exclude_patterns = ["api/*"]
|
||||
else:
|
||||
|
|
@ -189,21 +215,78 @@ else:
|
|||
|
||||
autodoc_default_options = {
|
||||
"members": True,
|
||||
"undoc-members": True,
|
||||
"undoc-members": False,
|
||||
"show-inheritance": True,
|
||||
"special-members": "__init__",
|
||||
"enable_eval_rst": True,
|
||||
# "inherited_members": True
|
||||
}
|
||||
|
||||
autodoc_member_order = "bysource"
|
||||
autodoc_typehints = "description"
|
||||
|
||||
|
||||
def autodoc_skip_member(app, what, name, obj, skip, options):
|
||||
"""Which members the autodoc should ignore."""
|
||||
if _no_autodoc:
|
||||
return True
|
||||
if name.startswith("__") and name != "__init__":
|
||||
if name.startswith("_") and name != "__init__":
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def autodoc_post_process_docstring(app, what, name, obj, options, lines):
|
||||
"""
|
||||
Post-process docstring in various ways. Must modify lines-list in-place.
|
||||
"""
|
||||
try:
|
||||
|
||||
# clean out ANSI colors
|
||||
|
||||
if ansi_clean:
|
||||
for il, line in enumerate(lines):
|
||||
lines[il] = ansi_clean(line)
|
||||
|
||||
# post-parse docstrings to convert any remaining
|
||||
# markdown -> reST since napoleon doesn't know Markdown
|
||||
|
||||
def _sub_codeblock(match):
|
||||
code = match.group(1)
|
||||
return "::\n\n {}".format(
|
||||
"\n ".join(lne for lne in code.split("\n")))
|
||||
|
||||
underline_map = {
|
||||
1: "-",
|
||||
2: "=",
|
||||
3: '^',
|
||||
4: '"',
|
||||
}
|
||||
|
||||
def _sub_header(match):
|
||||
# add underline to convert a markdown #header to ReST
|
||||
groupdict = match.groupdict()
|
||||
hashes, title = groupdict["hashes"], groupdict["title"]
|
||||
title = title.strip()
|
||||
lvl = min(max(1, len(hashes)), 4)
|
||||
return f"{title}\n" + (underline_map[lvl] * len(title))
|
||||
|
||||
doc = "\n".join(lines)
|
||||
doc = re.sub(r"```python\s*\n+(.*?)```", _sub_codeblock, doc,
|
||||
flags=re.MULTILINE + re.DOTALL)
|
||||
doc = re.sub(r"```", "", doc, flags=re.MULTILINE)
|
||||
doc = re.sub(r"`{1}", "**", doc, flags=re.MULTILINE)
|
||||
doc = re.sub(r"^(?P<hashes>#{1,2})\s*?(?P<title>.*?)$", _sub_header, doc, flags=re.MULTILINE)
|
||||
|
||||
newlines = doc.split("\n")
|
||||
# we must modify lines in-place
|
||||
lines[:] = newlines[:]
|
||||
|
||||
except Exception as err:
|
||||
# if we don't print here we won't see what the error actually is
|
||||
print(f"Post-process docstring exception: {err}")
|
||||
raise
|
||||
|
||||
|
||||
# Napoleon Google-style docstring parser for autodocs
|
||||
|
||||
napoleon_google_docstring = True
|
||||
|
|
@ -217,7 +300,7 @@ napoleon_use_admonition_for_references = False
|
|||
napoleon_use_ivar = False
|
||||
napoleon_use_param = True
|
||||
napoleon_use_keyword = True
|
||||
napoleon_use_rtype = True
|
||||
napoleon_use_rtype = False
|
||||
|
||||
|
||||
# -- Main config setup ------------------------------------------
|
||||
|
|
@ -226,8 +309,16 @@ napoleon_use_rtype = True
|
|||
|
||||
def setup(app):
|
||||
app.connect("autodoc-skip-member", autodoc_skip_member)
|
||||
app.connect("autodoc-process-docstring", autodoc_post_process_docstring)
|
||||
app.add_transform(AutoStructify)
|
||||
|
||||
# build toctree file
|
||||
sys.path.insert(1, os.path.join(os.path.dirname(os.path.dirname(__file__)), "docs"))
|
||||
from docs.pylib import auto_link_remapper
|
||||
|
||||
auto_link_remapper.auto_link_remapper()
|
||||
print("Updated source/toc.md file")
|
||||
|
||||
# custom lunr-based search
|
||||
# from docs import search
|
||||
# custom search
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue