Updated HTML docs.
This commit is contained in:
Griatch
parent
59e50f3fa5
commit
06bc3c8bcd
663 changed files with 2 additions and 61705 deletions
|
|
@ -1,32 +0,0 @@
|
|||
#!/usr/bin/python
|
||||
"""
|
||||
Remap autodoc API rst files to md files and wrap their contents.
|
||||
|
||||
"""
|
||||
|
||||
from glob import glob
|
||||
from os import rename
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as pathjoin
|
||||
|
||||
|
||||
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))
|
||||
|
|
@ -1,281 +0,0 @@
|
|||
"""
|
||||
Build a TOC-tree; Sphinx requires it and this makes it easy to just
|
||||
add/build/link new files without needing to explicitly add it to a toctree
|
||||
directive somewhere.
|
||||
|
||||
"""
|
||||
|
||||
import re
|
||||
from collections import defaultdict
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as pathjoin
|
||||
from os.path import relpath
|
||||
from pathlib import Path
|
||||
|
||||
from sphinx.errors import DocumentError
|
||||
|
||||
_IGNORE_FILES = []
|
||||
_SOURCEDIR_NAME = "source"
|
||||
_SOURCE_DIR = pathjoin(dirname(dirname(abspath(__file__))), _SOURCEDIR_NAME)
|
||||
_TOC_FILE = pathjoin(_SOURCE_DIR, "toc.md")
|
||||
_NO_REMAP_STARTSWITH = [
|
||||
"http://",
|
||||
"https://",
|
||||
"github:",
|
||||
"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",
|
||||
}
|
||||
URL_REMAPS = {
|
||||
"Developer-Central": "Components/Components-Overview",
|
||||
"Tutorials": "Howtos/Howtos-Overview",
|
||||
"../Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
|
||||
"Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
|
||||
"Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
|
||||
"Directory-Overview": "Gamedir-Overview",
|
||||
"../Setup/Getting-Started": "Setup-Quickstart",
|
||||
"Setup/Getting-Started": "Setup-Quickstart",
|
||||
"Getting-Started": "Setup-Quickstart",
|
||||
"First-Steps-Coding": "Beginner-Tutorial-Part1",
|
||||
"../Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
|
||||
"Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
|
||||
"Beginner-Tutorial/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",
|
||||
"modules": "Default-Commands.md",
|
||||
}
|
||||
|
||||
_USED_REFS = {}
|
||||
|
||||
_CURRFILE = None
|
||||
|
||||
|
||||
def auto_link_remapper(no_autodoc=False):
|
||||
"""
|
||||
- Auto-Remaps links to fit with the actual document file structure. Requires
|
||||
all doc files to have a unique name.
|
||||
- Creates source/toc.md file
|
||||
|
||||
"""
|
||||
global _CURRFILE
|
||||
|
||||
print(" -- Auto-Remapper starting.")
|
||||
|
||||
def _get_rel_source_ref(path):
|
||||
"""Get the path relative the source/ dir"""
|
||||
pathparts = path.split("/")
|
||||
# we allow a max of 4 levels of nesting in the source dir
|
||||
ind = pathparts[-5:].index(_SOURCEDIR_NAME)
|
||||
# get the part after source/
|
||||
pathparts = pathparts[-5 + 1 + ind :]
|
||||
url = "/".join(pathparts)
|
||||
# get the reference, without .md
|
||||
url = url.rsplit(".", 1)[0]
|
||||
return url
|
||||
|
||||
toc_map = {}
|
||||
docref_map = defaultdict(dict)
|
||||
|
||||
for path in Path(_SOURCE_DIR).rglob("*.md"):
|
||||
# find the source/ part of the path and strip it out
|
||||
|
||||
if path.name in _IGNORE_FILES:
|
||||
# this is the name including .md
|
||||
continue
|
||||
|
||||
sourcepath = path.as_posix()
|
||||
# get name and url relative to source/
|
||||
fname = path.name.rsplit(".", 1)[0]
|
||||
src_url = _get_rel_source_ref(sourcepath)
|
||||
|
||||
# check for duplicate files
|
||||
if fname in toc_map:
|
||||
duplicate_src_url = toc_map[fname]
|
||||
raise DocumentError(
|
||||
f" Tried to add {src_url}.md, but a file {duplicate_src_url}.md already exists.\n"
|
||||
" Evennia's auto-link-corrector does not accept doc-files with the same \n"
|
||||
" name, even in different folders. Rename one.\n"
|
||||
)
|
||||
toc_map[fname] = src_url
|
||||
|
||||
# find relative links to all other files
|
||||
for targetpath in Path(_SOURCE_DIR).rglob("*.md"):
|
||||
|
||||
targetname = targetpath.name.rsplit(".", 1)[0]
|
||||
targetpath = targetpath.as_posix()
|
||||
url = relpath(targetpath, dirname(sourcepath))
|
||||
if not "/" in url:
|
||||
# need to be explicit or there will be link ref collisions between
|
||||
# e.g. TickerHandler page and TickerHandle api node
|
||||
url = "./" + url
|
||||
docref_map[sourcepath][targetname] = url.rsplit(".", 1)[0]
|
||||
|
||||
# normal reference-links [txt](urls)
|
||||
ref_regex = re.compile(
|
||||
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>[\n\w -\`]+?)\]:\s+?(?P<url>.+?)(?=$|\n)", re.I + re.S + re.U + re.M
|
||||
)
|
||||
|
||||
def _sub(match):
|
||||
# inline reference links
|
||||
global _USED_REFS
|
||||
grpdict = match.groupdict()
|
||||
txt, url = grpdict["txt"], grpdict["url"]
|
||||
|
||||
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 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]
|
||||
|
||||
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] + ".md" + ("#" + anchor[0].lower() if anchor else "")
|
||||
)
|
||||
if urlout != url:
|
||||
print(f" {cfilename}: [{txt}]({url}) -> [{txt}]({urlout})")
|
||||
else:
|
||||
urlout = url
|
||||
|
||||
return f"[{txt}]({urlout})"
|
||||
|
||||
def _sub_doc(match):
|
||||
# reference links set at the bottom of the page
|
||||
global _USED_REFS
|
||||
grpdict = match.groupdict()
|
||||
txt, url = grpdict["txt"], grpdict["url"]
|
||||
|
||||
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
|
||||
fname = fname.rsplit(".", 1)[0]
|
||||
fname, *anchor = fname.rsplit("#", 1)
|
||||
|
||||
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
|
||||
|
||||
return f"[{txt}]: {urlout}"
|
||||
|
||||
# replace / correct links in all files
|
||||
count = 0
|
||||
for path in sorted(Path(_SOURCE_DIR).rglob("*.md"), key=lambda p: p.name):
|
||||
|
||||
# from pudb import debugger;debugger.Debugger().set_trace()
|
||||
_CURRFILE = path.as_posix()
|
||||
|
||||
with open(path, "r") as fil:
|
||||
intxt = fil.read()
|
||||
outtxt = ref_regex.sub(_sub, intxt)
|
||||
outtxt = ref_doc_regex.sub(_sub_doc, outtxt)
|
||||
if intxt != outtxt:
|
||||
with open(path, "w") as fil:
|
||||
fil.write(outtxt)
|
||||
count += 1
|
||||
print(f" -- Auto-relinked links in {path.name}")
|
||||
|
||||
if count > 0:
|
||||
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 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("```{toctree}\n")
|
||||
|
||||
# if not no_autodoc:
|
||||
# fil.write("- [API root](api/evennia-api.rst)")
|
||||
|
||||
# for ref in sorted(toc_map.values()):
|
||||
|
||||
# if ref == "toc":
|
||||
# continue
|
||||
|
||||
# # if not "/" in ref:
|
||||
# # ref = "./" + 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\n```{toctree}\n :hidden:\n\ntoc\n```")
|
||||
# print(" -- File toc.md updated.")
|
||||
|
||||
print(" -- Auto-Remapper finished.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
auto_link_remapper()
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
"""
|
||||
Builds a lunr static search index for optimized search
|
||||
|
||||
"""
|
||||
import glob
|
||||
import json
|
||||
import os
|
||||
from argparse import ArgumentParser
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as joinpath
|
||||
from os.path import sep
|
||||
|
||||
from lunr import lunr
|
||||
|
||||
_DOCS_PATH = dirname(dirname(abspath(__file__)))
|
||||
|
||||
_DEFAULT_BUILD_DIR = joinpath(_DOCS_PATH, "build", "html")
|
||||
_DEFAULT_URL_BASE = f"file://{_DEFAULT_BUILD_DIR}"
|
||||
_INDEX_PATH = joinpath("_static", "js", "lunr", "search_index.json")
|
||||
|
||||
DEFAULT_SOURCE_DIR = joinpath(_DOCS_PATH, "source")
|
||||
DEFAULT_OUTFILE = joinpath(DEFAULT_SOURCE_DIR, _INDEX_PATH)
|
||||
|
||||
URL_BASE = os.environ.get("SEARCH_URL_BASE", _DEFAULT_URL_BASE)
|
||||
|
||||
|
||||
def create_search_index(sourcedir, outfile):
|
||||
"""
|
||||
Create the index.
|
||||
|
||||
Args:
|
||||
sourcedir (str): Path to the source directory. This will be searched
|
||||
for both .md and .rst files.
|
||||
outfile (str): Path to the index file to create.
|
||||
|
||||
"""
|
||||
markdown_files = glob.glob(f"{sourcedir}{sep}*.md")
|
||||
markdown_files.extend(glob.glob(f"{sourcedir}{sep}*{sep}*.md"))
|
||||
rest_files = glob.glob(f"{sourcedir}{sep}*.rst")
|
||||
rest_files.extend(glob.glob(f"{sourcedir}{sep}*{sep}*.rst"))
|
||||
filepaths = markdown_files + rest_files
|
||||
|
||||
outlist = []
|
||||
|
||||
print(f"Building Search index from {len(filepaths)} files ... ", end="")
|
||||
|
||||
for filepath in filepaths:
|
||||
with open(filepath, "r") as fil:
|
||||
filename = filepath.rsplit(sep, 1)[1].split(".", 1)[0]
|
||||
url = f"{URL_BASE}{sep}{filename}.html".strip()
|
||||
title = filename.replace("-", " ").strip()
|
||||
body = fil.read()
|
||||
|
||||
data = {
|
||||
"url": url,
|
||||
"title": title,
|
||||
"text": body,
|
||||
}
|
||||
outlist.append(data)
|
||||
|
||||
idx = lunr(
|
||||
ref="url",
|
||||
documents=outlist,
|
||||
fields=[{"field_name": "title", "boost": 10}, {"field_name": "text", "boost": 1}],
|
||||
)
|
||||
|
||||
with open(outfile, "w") as fil:
|
||||
fil.write(json.dumps(idx.serialize()))
|
||||
|
||||
print(f"wrote to source{sep}{_INDEX_PATH}.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
parser = ArgumentParser(description="Build a static search index.")
|
||||
|
||||
parser.add_argument(
|
||||
"-i",
|
||||
dest="sourcedir",
|
||||
default=DEFAULT_SOURCE_DIR,
|
||||
help="Absolute path to the documentation source dir",
|
||||
)
|
||||
parser.add_argument(
|
||||
"-o",
|
||||
dest="outfile",
|
||||
default=DEFAULT_OUTFILE,
|
||||
help="Absolute path to the index file to output.",
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
create_search_index(args.sourcedir, args.outfile)
|
||||
|
|
@ -1,209 +0,0 @@
|
|||
"""
|
||||
Convert contribs' README files to proper documentation pages along with
|
||||
an index.
|
||||
|
||||
"""
|
||||
from collections import defaultdict
|
||||
from glob import glob
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as pathjoin
|
||||
from os.path import sep
|
||||
|
||||
_EVENNIA_PATH = pathjoin(dirname(dirname(dirname(abspath(__file__)))))
|
||||
_DOCS_PATH = pathjoin(_EVENNIA_PATH, "docs")
|
||||
|
||||
_SOURCE_DIR = pathjoin(_EVENNIA_PATH, "evennia", "contrib")
|
||||
_OUT_DIR = pathjoin(_DOCS_PATH, "source", "Contribs")
|
||||
_OUT_INDEX_FILE = pathjoin(_OUT_DIR, "Contribs-Overview.md")
|
||||
|
||||
_FILE_STRUCTURE = """{header}
|
||||
{categories}
|
||||
{footer}"""
|
||||
|
||||
_CATEGORY_DESCS = {
|
||||
"base_systems": """
|
||||
This category contains systems that are not necessarily tied to a specific
|
||||
in-game mechanic but is useful for the game as a whole. Examples include
|
||||
login systems, new command syntaxes, and build helpers.
|
||||
""",
|
||||
"full_systems": """
|
||||
This category contains 'complete' game engines that can be used directly
|
||||
to start creating content without no further additions (unless you want to).
|
||||
""",
|
||||
"game_systems": """
|
||||
This category holds code implementing in-game gameplay systems like
|
||||
crafting, mail, combat and more. Each system is meant to be adopted
|
||||
piecemeal and adopted for your game. This does not include
|
||||
roleplaying-specific systems, those are found in the `rpg` folder.
|
||||
""",
|
||||
"grid": """
|
||||
Systems related to the game world's topology and structure. This has
|
||||
contribs related to rooms, exits and map building.
|
||||
""",
|
||||
"rpg": """
|
||||
These are systems specifically related to roleplaying
|
||||
and rule implementation like character traits, dice rolling and emoting.
|
||||
""",
|
||||
"tutorials": """
|
||||
Helper resources specifically meant to teach a development concept or
|
||||
to exemplify an Evennia system. Any extra resources tied to documentation
|
||||
tutorials are found here. Also the home of the Tutorial World demo adventure.
|
||||
""",
|
||||
"utils": """
|
||||
Miscellaneous, optional tools for manipulating text, auditing connections
|
||||
and more.
|
||||
""",
|
||||
}
|
||||
|
||||
|
||||
_FILENAME_MAP = {"rpsystem": "RPSystem", "xyzgrid": "XYZGrid", "awsstorage": "AWSStorage"}
|
||||
|
||||
HEADER = """# Contribs
|
||||
|
||||
_Contribs_ are optional code snippets and systems contributed by
|
||||
the Evennia community. They vary in size and complexity and
|
||||
may be more specific about game types and styles than 'core' Evennia.
|
||||
This page is auto-generated and summarizes all contribs currently included.
|
||||
|
||||
All contrib categories are imported from `evennia.contrib`, such as
|
||||
|
||||
from evennia.contrib.base_systems import building_menu
|
||||
|
||||
Each contrib contains installation instructions for how to integrate it
|
||||
with your other code. If you want to tweak the code of a contrib, just
|
||||
copy its entire folder to your game directory and modify/use it from there.
|
||||
|
||||
> Hint: Additional (potentially un-maintained) code snippets from the community can be found
|
||||
in our discussion forum's [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets) category.
|
||||
|
||||
If you want to contribute yourself, see [here](Contributing)!
|
||||
"""
|
||||
|
||||
|
||||
TOCTREE = """```{{toctree}}
|
||||
:maxdepth: 1
|
||||
|
||||
{listing}
|
||||
```"""
|
||||
|
||||
CATEGORY = """
|
||||
## {category}
|
||||
|
||||
_{category_desc}_
|
||||
|
||||
{toctree}
|
||||
|
||||
{blurbs}
|
||||
|
||||
|
||||
"""
|
||||
|
||||
BLURB = """
|
||||
### Contrib: `{name}`
|
||||
|
||||
_{credits}_
|
||||
|
||||
{blurb}
|
||||
|
||||
[Read the documentation](./{filename}) - [Browse the Code](api:{code_location})
|
||||
|
||||
"""
|
||||
|
||||
FOOTER = """
|
||||
|
||||
----
|
||||
|
||||
<small>This document page is generated from `{path}`. Changes to this
|
||||
file will be overwritten, so edit that file rather than this one.</small>
|
||||
"""
|
||||
|
||||
INDEX_FOOTER = """
|
||||
|
||||
----
|
||||
|
||||
<small>This document page is auto-generated. Manual changes
|
||||
will be overwritten.</small>
|
||||
"""
|
||||
|
||||
|
||||
def readmes2docs(directory=_SOURCE_DIR):
|
||||
"""
|
||||
Parse directory for README files and convert them to doc pages.
|
||||
|
||||
"""
|
||||
|
||||
ncount = 0
|
||||
categories = defaultdict(list)
|
||||
|
||||
glob_path = f"{directory}{sep}*{sep}*{sep}README.md"
|
||||
|
||||
for file_path in glob(glob_path):
|
||||
# paths are e.g. evennia/contrib/utils/auditing/README.md
|
||||
_, category, name, _ = file_path.rsplit(sep, 3)
|
||||
|
||||
pypath = f"evennia.contrib.{category}.{name}"
|
||||
|
||||
filename = (
|
||||
"Contrib-"
|
||||
+ "-".join(
|
||||
_FILENAME_MAP.get(part, part.capitalize() if part[0].islower() else part)
|
||||
for part in name.split("_")
|
||||
)
|
||||
+ ".md"
|
||||
)
|
||||
outfile = pathjoin(_OUT_DIR, filename)
|
||||
|
||||
with open(file_path) as fil:
|
||||
data = fil.read()
|
||||
|
||||
clean_file_path = f"evennia{sep}contrib{file_path[len(directory):]}"
|
||||
data += FOOTER.format(path=clean_file_path)
|
||||
|
||||
try:
|
||||
credits = data.split("\n\n", 3)[1]
|
||||
blurb = data.split("\n\n", 3)[2]
|
||||
except IndexError:
|
||||
blurb = name
|
||||
|
||||
with open(outfile, "w") as fil:
|
||||
fil.write(data)
|
||||
|
||||
categories[category].append((name, credits, blurb, filename, pypath))
|
||||
ncount += 1
|
||||
|
||||
# build the index with blurbs
|
||||
|
||||
category_sections = []
|
||||
for category in sorted(categories):
|
||||
filenames = []
|
||||
contrib_tups = categories[category]
|
||||
catlines = []
|
||||
for tup in sorted(contrib_tups, key=lambda tup: tup[0].lower()):
|
||||
catlines.append(
|
||||
BLURB.format(
|
||||
name=tup[0], credits=tup[1], blurb=tup[2], filename=tup[3], code_location=tup[4]
|
||||
)
|
||||
)
|
||||
filenames.append(f"{tup[3]}")
|
||||
toctree = TOCTREE.format(listing="\n".join(filenames))
|
||||
category_sections.append(
|
||||
CATEGORY.format(
|
||||
category=category,
|
||||
category_desc=_CATEGORY_DESCS[category].strip(),
|
||||
blurbs="\n".join(catlines),
|
||||
toctree=toctree,
|
||||
)
|
||||
)
|
||||
|
||||
text = _FILE_STRUCTURE.format(
|
||||
header=HEADER, categories="\n".join(category_sections), footer=INDEX_FOOTER
|
||||
)
|
||||
|
||||
with open(_OUT_INDEX_FILE, "w") as fil:
|
||||
fil.write(text)
|
||||
|
||||
print(f" -- Converted Contrib READMEs to {ncount} doc pages + index.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
readmes2docs(_SOURCE_DIR)
|
||||
|
|
@ -1,279 +0,0 @@
|
|||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
"""
|
||||
Copy data from old Evennia github Wiki to static files.
|
||||
|
||||
Prepare files for mkdoc. This assumes evennia.wiki is cloned
|
||||
to a folder at the same level as the evennia repo.
|
||||
|
||||
Just run this to update everything.
|
||||
|
||||
We also need to build the toc-tree and should do so automatically for now.
|
||||
|
||||
"""
|
||||
|
||||
import datetime
|
||||
import glob
|
||||
import re
|
||||
|
||||
_RE_MD_LINK = re.compile(r"\[(?P<txt>[\w -\[\]]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U)
|
||||
_RE_REF_LINK = re.compile(r"\[[\w -\[\]]*?\]\(.+?\)", re.I + re.S + re.U)
|
||||
|
||||
_RE_CLEAN = re.compile(r"\|-+?|-+\|", re.I + re.S + re.U)
|
||||
|
||||
_IGNORE_FILES = (
|
||||
"_Sidebar.md",
|
||||
# "Wiki-Index.md"
|
||||
)
|
||||
|
||||
_INDEX_PREFIX = f"""
|
||||
|
||||
|
||||
# VERSION WARNING
|
||||
|
||||
> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the
|
||||
> [evennia wiki](https://github.com/evennia/evennia/wiki/) at {datetime.datetime.now()}.
|
||||
> There are known conversion issues which will _not_ be addressed in this version - refer to
|
||||
> the original wiki if you have trouble.
|
||||
>
|
||||
> Manual conversion and cleanup will instead happen during development of the upcoming v1.0
|
||||
> version of this static documentation.
|
||||
|
||||
"""
|
||||
|
||||
_WIKI_DIR = "../../../evennia.wiki/"
|
||||
_INFILES = [
|
||||
path
|
||||
for path in sorted(glob.glob(_WIKI_DIR + "/*.md"))
|
||||
if path.rsplit("/", 1)[-1] not in _IGNORE_FILES
|
||||
]
|
||||
_FILENAMES = [path.rsplit("/", 1)[-1] for path in _INFILES]
|
||||
_FILENAMES = [path.split(".", 1)[0] for path in _FILENAMES]
|
||||
_FILENAMESLOW = [path.lower() for path in _FILENAMES]
|
||||
_OUTDIR = "../source/"
|
||||
_OLD_WIKI_URL = "https://github.com/evennia/evennia/wiki/"
|
||||
_OLD_WIKI_URL_LEN = len(_OLD_WIKI_URL)
|
||||
_CODE_PREFIX = "github:"
|
||||
_API_PREFIX = "api:"
|
||||
|
||||
_CUSTOM_LINK_REMAP = {
|
||||
"CmdSets": "Command-Sets",
|
||||
"CmdSet": "Command-Sets",
|
||||
"Cmdsets": "Command-Sets",
|
||||
"CommandSet": "Command-Sets",
|
||||
"batch-code-processor": "Batch-Code-Processor",
|
||||
"Batch-code-processor": "Batch-Code-Processor",
|
||||
"batch-command-processor": "Batch-Command-Processor",
|
||||
"Batch-command-processor": "Batch-Command-Processor",
|
||||
"evennia-API": "Evennia-API",
|
||||
"Channels": "Communications#Channels",
|
||||
"Comms": "Communications",
|
||||
"typeclass": "Typeclasses",
|
||||
"Home": "index",
|
||||
"Help-system": "Help-System",
|
||||
"Using-Mux-as-a-Standard": "Using-MUX-as-a-Standard",
|
||||
"Building-quickstart": "Building-Quickstart",
|
||||
"Adding-Object-Typeclass-tutorial": "Adding-Object-Typeclass-Tutorial",
|
||||
"EvTable": _API_PREFIX + "evennia.utils#module-evennia.utils.evtable",
|
||||
}
|
||||
# complete reference remaps
|
||||
_REF_REMAP = {
|
||||
"[![Getting Started][icon_new]](Getting-Started)": "![Getting Started][icon_new]",
|
||||
"[![Admin Docs][icon_admin]](Administrative-Docs)": "![Admin Docs][icon_admin]",
|
||||
"[![Builder Docs][icon_builder]](Builder-Docs)": "![Builder Docs][icon_builder]",
|
||||
"[![Developer-Central][icon_devel]](Developer-Central)": "![Developer-Central][icon_devel]",
|
||||
"[![tutorial][icon_tutorial]](Tutorials)": "![Tutorials][icon_tutorial]",
|
||||
"[![API][icon_api]](evennia)": "![API][icon_api]",
|
||||
"[](Wiki-front-page.)": "",
|
||||
}
|
||||
|
||||
|
||||
# absolute links (mainly github links) that should not be converted. This
|
||||
# should be given without any #anchor.
|
||||
_ABSOLUTE_LINK_SKIP = (
|
||||
# "https://github.com/evennia/evennia/wiki/feature-request",
|
||||
)
|
||||
|
||||
# specific references tokens that should be ignored. Should be given
|
||||
# without any #anchor.
|
||||
_REF_SKIP = (
|
||||
"[5](Win)",
|
||||
"[6](Win)",
|
||||
"[7](Win)",
|
||||
"[10](Win)",
|
||||
"[11](Mac)",
|
||||
"[13](Win)",
|
||||
"[14](IOS)",
|
||||
"[15](IOS)",
|
||||
"[16](Andr)",
|
||||
"[17](Andr)",
|
||||
"[18](Unix)",
|
||||
"[21](Chrome)",
|
||||
# these should be checked
|
||||
"[EvTable](EvTable)",
|
||||
"[styled](OptionStyles)",
|
||||
"[Inputfunc](Inputfunc)",
|
||||
"[online documentation wiki](index)",
|
||||
"[online documentation](index)",
|
||||
"[Accounts](Account)",
|
||||
"[Session](Session)",
|
||||
"[Inputfuncs](Inputfunc)",
|
||||
)
|
||||
|
||||
|
||||
_CURRENT_TITLE = ""
|
||||
|
||||
|
||||
def _sub_remap(match):
|
||||
"""Total remaps"""
|
||||
ref = match.group(0)
|
||||
if ref in _REF_REMAP:
|
||||
new_ref = _REF_REMAP[ref]
|
||||
print(f" Replacing reference {ref} -> {new_ref}")
|
||||
return new_ref
|
||||
return ref
|
||||
|
||||
|
||||
def _sub_link(match):
|
||||
|
||||
mdict = match.groupdict()
|
||||
txt, url_orig = mdict["txt"], mdict["url"]
|
||||
url = url_orig
|
||||
# if not txt:
|
||||
# # the 'comment' is not supported by Mkdocs
|
||||
# return ""
|
||||
print(f" [{txt}]({url})")
|
||||
|
||||
url = _CUSTOM_LINK_REMAP.get(url, url)
|
||||
|
||||
url, *anchor = url.rsplit("#", 1)
|
||||
|
||||
if url in _ABSOLUTE_LINK_SKIP:
|
||||
url += ("#" + anchor[0]) if anchor else ""
|
||||
return f"[{txt}]({url})"
|
||||
|
||||
if url.startswith("evennia"):
|
||||
print(f" Convert evennia url {url} -> {_CODE_PREFIX + url}")
|
||||
url = _API_PREFIX + url
|
||||
|
||||
if url.startswith(_OLD_WIKI_URL):
|
||||
# old wiki is an url on the form https://<wikiurl>/wiki/TextTags#header
|
||||
# we don't refer to the old wiki but use internal mapping.
|
||||
if len(url) != len(_OLD_WIKI_URL):
|
||||
url_conv = url[_OLD_WIKI_URL_LEN:]
|
||||
url_conv = re.sub(r"%20", "-", url_conv)
|
||||
if url_conv.endswith("/_edit"):
|
||||
# this is actually a bug in the wiki format
|
||||
url_conv = url_conv[:-6]
|
||||
if url_conv.startswith("evennia"):
|
||||
# this is an api link
|
||||
url_conv = _CODE_PREFIX + url_conv
|
||||
|
||||
print(f" Converting wiki-url: {url} -> {url_conv}")
|
||||
url = url_conv
|
||||
|
||||
if not url and anchor:
|
||||
# this happens on same-file #labels in wiki
|
||||
url = _CURRENT_TITLE
|
||||
|
||||
if url not in _FILENAMES and not url.startswith("http") and not url.startswith(_CODE_PREFIX):
|
||||
|
||||
url_cap = url.capitalize()
|
||||
url_plur = url[:-3] + "s" + ".md"
|
||||
url_cap_plur = url_plur.capitalize()
|
||||
|
||||
link = f"[{txt}]({url})"
|
||||
if link in _REF_SKIP:
|
||||
url = link
|
||||
elif url_cap in _FILENAMES:
|
||||
print(f" Replacing (capitalized): {url.capitalize()}")
|
||||
url = url_cap
|
||||
elif url_plur in _FILENAMES:
|
||||
print(f" Replacing (pluralized): {url + 's'}")
|
||||
url = url_plur
|
||||
elif url_cap_plur in _FILENAMES:
|
||||
print(f" Replacing (capitalized, pluralized): {url.capitalize() + 's'}")
|
||||
url = url_cap_plur
|
||||
elif url.lower() in _FILENAMESLOW:
|
||||
ind = _FILENAMESLOW.index(url.lower())
|
||||
alt = _FILENAMES[ind]
|
||||
print(f" Replacing {url} with different cap: {alt}")
|
||||
url = alt
|
||||
|
||||
# print(f"\nlink {link} (orig: [{txt}]({url_orig})) found no file match")
|
||||
# inp = input("Enter alternate url (return to keep old): ")
|
||||
# if inp.strip():
|
||||
# url = inp.strip()
|
||||
|
||||
if anchor:
|
||||
url += "#" + anchor[0]
|
||||
|
||||
return f"[{txt}]({url})"
|
||||
|
||||
|
||||
def create_toctree(files):
|
||||
with open("../source/toc.md", "w") as fil:
|
||||
fil.write("# Toc\n")
|
||||
|
||||
for path in files:
|
||||
filename = path.rsplit("/", 1)[-1]
|
||||
ref = filename.rsplit(".", 1)[0]
|
||||
linkname = ref.replace("-", " ")
|
||||
|
||||
if ref == "Home":
|
||||
ref = "index"
|
||||
|
||||
fil.write(f"\n* [{linkname}]({ref}.md)")
|
||||
|
||||
|
||||
def convert_links(files, outdir):
|
||||
global _CURRENT_TITLE
|
||||
|
||||
for inpath in files:
|
||||
|
||||
is_index = False
|
||||
outfile = inpath.rsplit("/", 1)[-1]
|
||||
if outfile == "Home.md":
|
||||
outfile = "index.md"
|
||||
is_index = True
|
||||
outfile = _OUTDIR + outfile
|
||||
|
||||
title = inpath.rsplit("/", 1)[-1].split(".", 1)[0].replace("-", " ")
|
||||
|
||||
print(f"Converting links in {inpath} -> {outfile} ...")
|
||||
with open(inpath) as fil:
|
||||
text = fil.read()
|
||||
|
||||
if is_index:
|
||||
text = _INDEX_PREFIX + text
|
||||
lines = text.split("\n")
|
||||
lines = (
|
||||
lines[:-11]
|
||||
+ [" - The [TOC](toc) lists all regular documentation pages.\n\n"]
|
||||
+ lines[-11:]
|
||||
)
|
||||
text = "\n".join(lines)
|
||||
|
||||
_CURRENT_TITLE = title.replace(" ", "-")
|
||||
text = _RE_CLEAN.sub("", text)
|
||||
text = _RE_REF_LINK.sub(_sub_remap, text)
|
||||
text = _RE_MD_LINK.sub(_sub_link, text)
|
||||
text = (
|
||||
text.split("\n")[1:]
|
||||
if text.split("\n")[0].strip().startswith("[]")
|
||||
else text.split("\n")
|
||||
)
|
||||
text = "\n".join(text)
|
||||
|
||||
if not is_index:
|
||||
text = f"# {title}\n\n{text}"
|
||||
|
||||
with open(outfile, "w") as fil:
|
||||
fil.write(text)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("This should not be run on develop files, it would overwrite changes.")
|
||||
# create_toctree(_INFILES)
|
||||
# convert_links(_INFILES, _OUTDIR)
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
#!/usr/bin python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
"""
|
||||
Format given files to a max width.
|
||||
|
||||
Usage:
|
||||
python fmtwidth.py --width 79 ../source/**.md
|
||||
|
||||
"""
|
||||
import argparse
|
||||
import glob
|
||||
import textwrap
|
||||
|
||||
_DEFAULT_WIDTH = 100
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
parser = argparse.ArgumentParser()
|
||||
|
||||
parser.add_argument("files")
|
||||
parser.add_argument("-w", "--width", dest="width", type=int, default=_DEFAULT_WIDTH)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
filepaths = glob.glob(args.files, recursive=True)
|
||||
width = args.width
|
||||
|
||||
wrapper = textwrap.TextWrapper(
|
||||
width=width,
|
||||
break_long_words=False,
|
||||
expand_tabs=True,
|
||||
)
|
||||
|
||||
count = 0
|
||||
for filepath in filepaths:
|
||||
with open(filepath, "r") as fil:
|
||||
lines = fil.readlines()
|
||||
|
||||
outlines = [
|
||||
"\n".join(wrapper.wrap(line)) if len(line) > width else line.strip("\n")
|
||||
for line in lines
|
||||
]
|
||||
txt = "\n".join(outlines)
|
||||
with open(filepath, "w") as fil:
|
||||
fil.write(txt)
|
||||
count += 1
|
||||
|
||||
print(f"Wrapped {count} files.")
|
||||
|
|
@ -1,120 +0,0 @@
|
|||
"""
|
||||
|
||||
Generates Components/Default-Commands.md from sources.
|
||||
|
||||
To test - import this from a Django-aware shell, then call run_update.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as pathjoin
|
||||
|
||||
from evennia.utils.utils import (callables_from_module, mod_import,
|
||||
variable_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 how to 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 add 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}
|
||||
|
||||
""".strip()
|
||||
|
||||
|
||||
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 = [
|
||||
alias[1:] if alias and alias[0] == "@" else alias for alias in sorted(cmd.aliases)
|
||||
]
|
||||
aliases = f" [{', '.join(sorted(cmd.aliases))}]" if aliases else ""
|
||||
cmdlink = f"[**{cmd.key}**{aliases}](api:{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}](api:{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()
|
||||
|
|
@ -1,83 +0,0 @@
|
|||
"""
|
||||
Update dynamically generated doc pages based on github sources.
|
||||
|
||||
"""
|
||||
|
||||
from os.path import abspath, dirname
|
||||
from os.path import join as pathjoin
|
||||
|
||||
ROOTDIR = dirname(dirname(dirname(abspath(__file__))))
|
||||
DOCDIR = pathjoin(ROOTDIR, "docs")
|
||||
DOCSRCDIR = pathjoin(DOCDIR, "source")
|
||||
EVENNIADIR = pathjoin(ROOTDIR, "evennia")
|
||||
|
||||
|
||||
def update_changelog():
|
||||
"""
|
||||
Plain CHANGELOG copy
|
||||
|
||||
"""
|
||||
|
||||
sourcefile = pathjoin(ROOTDIR, "CHANGELOG.md")
|
||||
targetfile = pathjoin(DOCSRCDIR, "Coding", "Changelog.md")
|
||||
|
||||
with open(sourcefile) as fil:
|
||||
txt = fil.read()
|
||||
|
||||
with open(targetfile, "w") as fil:
|
||||
fil.write(txt)
|
||||
|
||||
print(" -- Updated Changelog.md")
|
||||
|
||||
|
||||
def update_default_settings():
|
||||
"""
|
||||
Make a copy of the default settings file for easy reference in docs
|
||||
|
||||
"""
|
||||
|
||||
sourcefile = pathjoin(EVENNIADIR, "settings_default.py")
|
||||
targetfile = pathjoin(DOCSRCDIR, "Setup", "Settings-Default.md")
|
||||
|
||||
with open(sourcefile) as fil:
|
||||
txt = fil.read()
|
||||
|
||||
txt = f"""
|
||||
# Evennia Default settings file
|
||||
|
||||
Master file is located at `evennia/evennia/settings_default.py`. Read
|
||||
its comments to see what each setting does and copy only what you want
|
||||
to change into `mygame/server/conf/settings.py`.
|
||||
|
||||
Example of accessing settings:
|
||||
|
||||
```
|
||||
from django.conf import settings
|
||||
|
||||
if settings.SERVERNAME == "Evennia":
|
||||
print("Yay!")
|
||||
```
|
||||
|
||||
----
|
||||
|
||||
```python
|
||||
{txt}
|
||||
```
|
||||
"""
|
||||
with open(targetfile, "w") as fil:
|
||||
fil.write(txt)
|
||||
|
||||
print(" -- Updated Settings-Default.md")
|
||||
|
||||
|
||||
def update_dynamic_pages():
|
||||
"""
|
||||
Run the various updaters
|
||||
|
||||
"""
|
||||
update_changelog()
|
||||
update_default_settings()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
update_dynamic_pages()
|
||||
Loading…
Add table
Add a link
Reference in a new issue