Convert master docs to use MyST
This commit is contained in:
Griatch
parent
6e03216cd9
commit
d229ff024c
359 changed files with 3275 additions and 4567 deletions
|
|
@ -9,7 +9,7 @@ import re
|
|||
from collections import defaultdict
|
||||
from sphinx.errors import DocumentError
|
||||
from pathlib import Path
|
||||
from os.path import abspath, dirname, join as pathjoin, sep, relpath
|
||||
from os.path import abspath, dirname, join as pathjoin, relpath
|
||||
|
||||
_IGNORE_FILES = []
|
||||
_SOURCEDIR_NAME = "source"
|
||||
|
|
@ -19,15 +19,54 @@ _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 = {}
|
||||
URL_REMAPS = {}
|
||||
# "Developer Central": "Evennia Components overview",
|
||||
# "Getting Started": "Setup Quickstart",
|
||||
# }
|
||||
URL_REMAPS = {
|
||||
"Default-Command-Help": "Default-Commands",
|
||||
"./Default-Command-Help.md": "Default-Commands.md"
|
||||
}
|
||||
# "Developer-Central": "Components/Components-Overview",
|
||||
# "Tutorials": "Howto/Howto-Overview",
|
||||
# "../Howto/Starting/Directory-Overview": "Gamedir-Overview",
|
||||
# "Howto/Starting/Directory-Overview": "Gamedir-Overview",
|
||||
# "Starting/Directory-Overview": "Gamedir-Overview",
|
||||
# "Directory-Overview": "Gamedir-Overview",
|
||||
# "../Setup/Getting-Started": "Setup-Quickstart",
|
||||
# "Setup/Getting-Started": "Setup-Quickstart",
|
||||
# "Setup-Quickstart": "Setup-Quickstart",
|
||||
# "Setup-Quickstart": "Getting-Started", # back again
|
||||
# "First-Steps-Coding": "Starting-Part1",
|
||||
# "../Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
|
||||
# "Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
|
||||
# "Starting/Adding-Command-Tutorial": "Adding-Commands",
|
||||
# "Adding-Command-Tutorial": "Adding-Commands",
|
||||
# "CmdSet": "Command-Sets",
|
||||
# "Spawner": "Prototypes",
|
||||
# "issue": "github:issue",
|
||||
# "issues": "github:issue",
|
||||
# "bug": "github:issue",
|
||||
# "bug-report": "github:issue",
|
||||
# "./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",
|
||||
# "Permissions": "./Locks.md#permissions", # back again
|
||||
# }
|
||||
|
||||
_USED_REFS = {}
|
||||
|
||||
|
|
@ -96,11 +135,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):
|
||||
|
|
@ -112,27 +151,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})"
|
||||
|
||||
|
|
@ -145,11 +195,21 @@ 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}"
|
||||
|
||||
urlout = 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
|
||||
|
|
@ -190,12 +250,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)")
|
||||
|
|
@ -205,17 +265,14 @@ def auto_link_remapper(no_autodoc=False):
|
|||
if ref == "toc":
|
||||
continue
|
||||
|
||||
if "Part1/" in ref:
|
||||
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.")
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue