Change to MyST parser
This commit is contained in:
Griatch
parent
53106e1dba
commit
a51e4af609
443 changed files with 4925 additions and 3524 deletions
31
docs/pylib/api_rst2md.py
Executable file
31
docs/pylib/api_rst2md.py
Executable file
|
|
@ -0,0 +1,31 @@
|
|||
#!/usr/bin/python
|
||||
"""
|
||||
Remap autodoc API rst files to md files and wrap their contents.
|
||||
|
||||
"""
|
||||
|
||||
from glob import glob
|
||||
from os.path import abspath, join as pathjoin, dirname
|
||||
from os import rename
|
||||
|
||||
|
||||
def _rst2md(filename_rst):
|
||||
|
||||
with open(filename_rst, 'r') as fil:
|
||||
# read rst file, reformat and save
|
||||
txt = fil.read()
|
||||
with open(filename_rst, 'w') as fil:
|
||||
txt = "```{eval-rst}\n" + txt + "\n```"
|
||||
fil.write(txt)
|
||||
|
||||
# rename .rst file to .md file
|
||||
filename, _ = filename_rst.rsplit('.', 1)
|
||||
filename_md = filename + ".md"
|
||||
rename(filename_rst, filename_md)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
apidir = pathjoin(dirname(dirname(abspath(__file__))), "source", "api")
|
||||
for filename_rst in glob(pathjoin(apidir, "*.rst")):
|
||||
_rst2md(filename_rst)
|
||||
print(" Converted {apidir}/*.rst files to .md files".format(apidir=apidir))
|
||||
|
|
@ -19,13 +19,19 @@ _NO_REMAP_STARTSWITH = [
|
|||
"http://",
|
||||
"https://",
|
||||
"github:",
|
||||
"api:",
|
||||
"feature-request",
|
||||
"report-bug",
|
||||
"issue",
|
||||
"bug-report",
|
||||
]
|
||||
|
||||
# remove these prefixes from the url
|
||||
_STRIP_PREFIX = [
|
||||
"../../api/",
|
||||
"../api/",
|
||||
"./api/",
|
||||
"api/",
|
||||
"api:",
|
||||
]
|
||||
TXT_REMAPS = {
|
||||
"Developer Central": "Evennia Components overview",
|
||||
"Getting Started": "Setup Quickstart",
|
||||
|
|
@ -54,6 +60,8 @@ URL_REMAPS = {
|
|||
"./Default-Command-Help": "api:evennia.commands.default#modules",
|
||||
"../Components/Default-Command-Help": "api:evennia.commands.default#modules",
|
||||
"../../../Components/Default-Command-Help": "api:evennia.commands.default#modules",
|
||||
"./Locks.md#permissions": "Permissions",
|
||||
"modules": "Default-Commands.md",
|
||||
}
|
||||
|
||||
_USED_REFS = {}
|
||||
|
|
@ -123,11 +131,11 @@ def auto_link_remapper(no_autodoc=False):
|
|||
|
||||
# normal reference-links [txt](urls)
|
||||
ref_regex = re.compile(
|
||||
r"\[(?P<txt>[\w -\[\]\`]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U + re.M
|
||||
r"\[(?P<txt>[\n\w -\[\]\`]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U + re.M
|
||||
)
|
||||
# in document references
|
||||
ref_doc_regex = re.compile(
|
||||
r"\[(?P<txt>[\w -\`]+?)\]:\s+?(?P<url>.+?)(?=$|\n)", re.I + re.S + re.U + re.M
|
||||
r"\[(?P<txt>[\n\w -\`]+?)\]:\s+?(?P<url>.+?)(?=$|\n)", re.I + re.S + re.U + re.M
|
||||
)
|
||||
|
||||
def _sub(match):
|
||||
|
|
@ -139,27 +147,38 @@ def auto_link_remapper(no_autodoc=False):
|
|||
txt = TXT_REMAPS.get(txt, txt)
|
||||
url = URL_REMAPS.get(url, url)
|
||||
|
||||
for strip_prefix in _STRIP_PREFIX:
|
||||
if url.startswith(strip_prefix):
|
||||
url = url[len(strip_prefix):]
|
||||
|
||||
if any(url.startswith(noremap) for noremap in _NO_REMAP_STARTSWITH):
|
||||
# skip regular http/s urls etc
|
||||
return f"[{txt}]({url})"
|
||||
|
||||
if "http" in url and "://" in url:
|
||||
urlout = url
|
||||
else:
|
||||
fname, *part = url.rsplit("/", 1)
|
||||
fname = part[0] if part else fname
|
||||
if url.startswith("evennia."):
|
||||
# api link - we want to remove legacy #reference and remove .md
|
||||
if '#' in url:
|
||||
_, url = url.rsplit('#', 1)
|
||||
if url.endswith(".md"):
|
||||
url, _ = url.rsplit('.', 1)
|
||||
return f"[{txt}]({url})"
|
||||
|
||||
fname, *part = url.rsplit("/", 1)
|
||||
fname = part[0] if part else fname
|
||||
fname, *anchor = fname.rsplit("#", 1)
|
||||
if ".md" in fname:
|
||||
fname = fname.rsplit(".", 1)[0]
|
||||
fname, *anchor = fname.rsplit("#", 1)
|
||||
|
||||
if not _CURRFILE.endswith("toc.md"):
|
||||
_USED_REFS[fname] = url
|
||||
if not _CURRFILE.endswith("toc.md"):
|
||||
_USED_REFS[fname] = url
|
||||
|
||||
if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]:
|
||||
cfilename = _CURRFILE.rsplit("/", 1)[-1]
|
||||
urlout = docref_map[_CURRFILE][fname] + ("#" + anchor[0] if anchor else "")
|
||||
if urlout != url:
|
||||
print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})")
|
||||
else:
|
||||
urlout = url
|
||||
if _CURRFILE in docref_map and fname in docref_map[_CURRFILE]:
|
||||
cfilename = _CURRFILE.rsplit("/", 1)[-1]
|
||||
urlout = docref_map[_CURRFILE][fname] + ".md" + ("#" + anchor[0].lower() if anchor else "")
|
||||
if urlout != url:
|
||||
print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})")
|
||||
else:
|
||||
urlout = url
|
||||
|
||||
return f"[{txt}]({urlout})"
|
||||
|
||||
|
|
@ -172,11 +191,19 @@ def auto_link_remapper(no_autodoc=False):
|
|||
txt = TXT_REMAPS.get(txt, txt)
|
||||
url = URL_REMAPS.get(url, url)
|
||||
|
||||
for strip_prefix in _STRIP_PREFIX:
|
||||
if url.startswith(strip_prefix):
|
||||
url = url[len(strip_prefix):]
|
||||
|
||||
if any(url.startswith(noremap) for noremap in _NO_REMAP_STARTSWITH):
|
||||
return f"[{txt}]: {url}"
|
||||
|
||||
if "http" in url and "://" in url:
|
||||
urlout = url
|
||||
elif url.startswith("evennia."):
|
||||
# api link - we want to remove legacy #reference
|
||||
if '#' in url:
|
||||
_, urlout = url.rsplit('#', 1)
|
||||
else:
|
||||
fname, *part = url.rsplit("/", 1)
|
||||
fname = part[0] if part else fname
|
||||
|
|
@ -217,12 +244,12 @@ def auto_link_remapper(no_autodoc=False):
|
|||
print(f" -- Auto-corrected links in {count} documents.")
|
||||
|
||||
for (fname, src_url) in sorted(toc_map.items(), key=lambda tup: tup[0]):
|
||||
if fname not in _USED_REFS:
|
||||
if fname not in _USED_REFS and not src_url.startswith("api/"):
|
||||
print(f" ORPHANED DOC: no refs found to {src_url}.md")
|
||||
|
||||
# write tocfile
|
||||
with open(_TOC_FILE, "w") as fil:
|
||||
fil.write("# Toc\n")
|
||||
fil.write("```{toctree}\n")
|
||||
|
||||
if not no_autodoc:
|
||||
fil.write("- [API root](api/evennia-api.rst)")
|
||||
|
|
@ -232,14 +259,14 @@ def auto_link_remapper(no_autodoc=False):
|
|||
if ref == "toc":
|
||||
continue
|
||||
|
||||
if not "/" in ref:
|
||||
ref = "./" + ref
|
||||
# if not "/" in ref:
|
||||
# ref = "./" + ref
|
||||
|
||||
linkname = ref.replace("-", " ")
|
||||
fil.write(f"\n- [{linkname}]({ref})")
|
||||
# linkname = ref.replace("-", " ")
|
||||
fil.write(f"\n{ref}") # - [{linkname}]({ref})")
|
||||
|
||||
# we add a self-reference so the toc itself is also a part of a toctree
|
||||
fil.write("\n\n```toctree::\n :hidden:\n\n toc\n```")
|
||||
fil.write("\n```\n\n```{toctree}\n :hidden:\n\ntoc\n```")
|
||||
|
||||
print(" -- Auto-Remapper finished.")
|
||||
|
||||
|
|
|
|||
111
docs/pylib/update_default_cmd_index.py
Normal file
111
docs/pylib/update_default_cmd_index.py
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
#
|
||||
# This creates a Google wiki page for all default commands with __doc__ strings.
|
||||
#
|
||||
# Import this from a Django-aware shell, then call run_update.
|
||||
#
|
||||
#
|
||||
|
||||
from os.path import dirname, abspath, join as pathjoin
|
||||
from evennia.utils.utils import (
|
||||
mod_import, variable_from_module, callables_from_module
|
||||
)
|
||||
|
||||
__all__ = ("run_update")
|
||||
|
||||
|
||||
PAGE = """
|
||||
|
||||
# Default Commands
|
||||
|
||||
The full set of default Evennia commands currently contains {ncommands} commands in {nfiles} source
|
||||
files. Our policy for adding default commands is outlined [here](Using-MUX-as-a-Standard). The
|
||||
[Commands](Commands) documentation explains how Commands work as well as make new or customize
|
||||
existing ones. Note that this page is auto-generated. Report problems to the [issue
|
||||
tracker](github:issues).
|
||||
|
||||
```{{note}}
|
||||
Some game-states adds their own Commands which are not listed here. Examples include editing a text
|
||||
with [EvEditor](EvEditor), flipping pages in [EvMore](EvMore) or using the
|
||||
[Batch-Processor](Batch-Processors)'s interactive mode.
|
||||
```
|
||||
|
||||
{alphabetical}
|
||||
|
||||
"""
|
||||
|
||||
def run_update(no_autodoc=False):
|
||||
|
||||
if no_autodoc:
|
||||
return
|
||||
|
||||
cmdsets = (
|
||||
("evennia.commands.default.cmdset_character", "CharacterCmdSet"),
|
||||
("evennia.commands.default.cmdset_account", "AccountCmdSet"),
|
||||
("evennia.commands.default.cmdset_unloggedin", "UnloggedinCmdSet"),
|
||||
("evennia.commands.default.cmdset_session", "SessionCmdSet"),
|
||||
)
|
||||
cmd_modules = (
|
||||
"evennia.commands.default.account",
|
||||
"evennia.commands.default.batchprocess",
|
||||
"evennia.commands.default.building",
|
||||
"evennia.commands.default.comms",
|
||||
"evennia.commands.default.general",
|
||||
"evennia.commands.default.help",
|
||||
"evennia.commands.default.syscommandsyyp",
|
||||
"evennia.commands.default.system",
|
||||
"evennia.commands.default.unloggedin",
|
||||
)
|
||||
|
||||
cmds_per_cmdset = {}
|
||||
cmd_to_cmdset_map = {}
|
||||
for modname, cmdsetname in cmdsets:
|
||||
cmdset = variable_from_module(modname, variable=cmdsetname)()
|
||||
cmdset.at_cmdset_creation()
|
||||
cmds_per_cmdset[cmdsetname] = cmdset.commands
|
||||
for cmd in cmdset.commands:
|
||||
cmd_to_cmdset_map[f"{cmd.__module__}.{cmd.__class__.__name__}"] = cmdset
|
||||
|
||||
cmds_per_module = {}
|
||||
cmd_to_module_map = {}
|
||||
cmds_alphabetically = []
|
||||
for modname in cmd_modules:
|
||||
module = mod_import(modname)
|
||||
cmds_per_module[module] = [
|
||||
cmd for cmd in callables_from_module(module).values() if cmd.__name__.startswith("Cmd")]
|
||||
for cmd in cmds_per_module[module]:
|
||||
cmd_to_module_map[cmd] = module
|
||||
cmds_alphabetically.append(cmd)
|
||||
cmds_alphabetically = list(sorted(cmds_alphabetically, key=lambda c: c.key))
|
||||
|
||||
cmd_infos = []
|
||||
for cmd in cmds_alphabetically:
|
||||
aliases = f" [{', '.join(cmd.aliases)}]" if cmd.aliases else ""
|
||||
cmdlink = f"[**{cmd.key}**{aliases}]({cmd.__module__}.{cmd.__name__})"
|
||||
category = f"help-category: _{cmd.help_category.capitalize()}_"
|
||||
cmdset = cmd_to_cmdset_map.get(f"{cmd.__module__}.{cmd.__name__}", None)
|
||||
if cmdset:
|
||||
cmodule = cmdset.__module__
|
||||
cname = cmdset.__class__.__name__
|
||||
cmdsetlink = f"cmdset: [{cname}]({cmodule}.{cname}), "
|
||||
else:
|
||||
# we skip commands not in the default cmdsets
|
||||
continue
|
||||
|
||||
cmd_infos.append(f"{cmdlink} ({cmdsetlink}{category})")
|
||||
|
||||
txt = PAGE.format(
|
||||
ncommands=len(cmd_to_cmdset_map),
|
||||
nfiles=len(cmds_per_module),
|
||||
alphabetical="\n".join(f"- {info}" for info in cmd_infos))
|
||||
|
||||
outdir = pathjoin(dirname(dirname(abspath(__file__))), "source", "Components")
|
||||
fname = pathjoin(outdir, "Default-Commands.md")
|
||||
|
||||
with open(fname, 'w') as fil:
|
||||
fil.write(txt)
|
||||
|
||||
print(" -- Updated Default Command index.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
run_update()
|
||||
Loading…
Add table
Add a link
Reference in a new issue