Merge pull request #29 from python-discord/port-utilities

Port utilities

1 files changed, 17 insertions, 108 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 4ab831d3..476a4d36 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,17 +1,20 @@
 # Configuration file for the Sphinx documentation builder.
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-import ast
-import importlib
-import inspect
+import functools
+import os.path
 import sys
-import typing
 from pathlib import Path
 
 import git
 import tomli
 from sphinx.application import Sphinx
 
+# Handle the path not being set correctly in actions.
+sys.path.insert(0, os.path.abspath('..'))
+
+from docs import utils  # noqa: E402
+
 # -- Project information -----------------------------------------------------
 
 project = "Bot Core"
@@ -38,11 +41,11 @@ add_module_names = False
 # ones.
 extensions = [
     "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
-    "releases",
     "sphinx.ext.linkcode",
     "sphinx.ext.githubpages",
 ]
@@ -80,52 +83,10 @@ html_logo = "https://raw.githubusercontent.com/python-discord/branding/main/logo
 html_favicon = html_logo
 
 html_css_files = [
-    "changelog.css",
     "logo.css",
 ]
 
-html_js_files = [
-    "changelog.js",
-]
-
-
-# -- Autodoc cleanup ---------------------------------------------------------
-# Clean up the output generated by autodoc to produce a nicer documentation tree
-# This is kept in a function to avoid polluting the namespace
-def __cleanup() -> None:
-    for file in (PROJECT_ROOT / "docs" / "output").iterdir():
-        if file.name == "modules.rst":
-            # We only have one module, so this is redundant
-            # Remove it and flatten out the tree
-            file.unlink()
-
-        elif file.name == "botcore.rst":
-            # We want to bring the submodule name to the top, and remove anything that's not a submodule
-            result = ""
-            for line in file.read_text(encoding="utf-8").splitlines(keepends=True):
-                if ".." not in line and result == "":
-                    # We have not reached the first submodule, this is all filler
-                    continue
-                elif "Module contents" in line:
-                    # We have parsed all the submodules, so let's skip the redudant module name
-                    break
-                result += line
-
-            result = "Botcore\n=======\n\n" + result
-            file.write_text(result, encoding="utf-8")
-
-        else:
-            # Clean up the submodule name so it's just the name without the top level module name
-            # example: `botcore.regex module` -> `regex`
-            lines = file.read_text(encoding="utf-8").splitlines()
-            lines[0] = lines[0].replace("botcore.", "").replace("module", "").strip()
-
-            # Take the opportunity to configure autodoc
-            lines = "\n".join(lines).replace("undoc-members", "special-members")
-            file.write_text(lines, encoding="utf-8")
-
-
-__cleanup()
+utils.cleanup()
 
 
 def skip(*args) -> bool:
@@ -159,70 +120,18 @@ napoleon_numpy_docstring = False
 napoleon_attr_annotations = True
 
 
-# -- Options for releases extension ------------------------------------------
-releases_github_path = REPO_LINK.removeprefix("https://github.com/")
-
-
 # -- Options for extlinks extension ------------------------------------------
 extlinks = {
     "repo-file": (f"{REPO_LINK}/blob/main/%s", "repo-file %s")
 }
 
 
+# -- Options for intersphinx extension ---------------------------------------
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "discord": ("https://discordpy.readthedocs.io/en/master/", None),
+}
+
+
 # -- Options for the linkcode extension --------------------------------------
-def linkcode_resolve(domain: str, info: dict[str, str]) -> typing.Optional[str]:
-    """
-    Function called by linkcode to get the URL for a given resource.
-
-    See for more details:
-    https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html#confval-linkcode_resolve
-    """
-    if domain != "py":
-        raise Exception("Unknown domain passed to linkcode function.")
-
-    symbol_name = info["fullname"]
-
-    module = importlib.import_module(info["module"])
-
-    symbol = [module]
-    for name in symbol_name.split("."):
-        symbol.append(getattr(symbol[-1], name))
-        symbol_name = name
-
-    try:
-        lines, start = inspect.getsourcelines(symbol[-1])
-        end = start + len(lines)
-    except TypeError:
-        # Find variables by parsing the ast
-        source = ast.parse(inspect.getsource(symbol[-2]))
-        while isinstance(source.body[0], ast.ClassDef):
-            source = source.body[0]
-
-        for ast_obj in source.body:
-            if isinstance(ast_obj, ast.Assign):
-                names = []
-                for target in ast_obj.targets:
-                    if isinstance(target, ast.Tuple):
-                        names.extend([name.id for name in target.elts])
-                    else:
-                        names.append(target.id)
-
-                if symbol_name in names:
-                    start, end = ast_obj.lineno, ast_obj.end_lineno
-                    break
-        else:
-            raise Exception(f"Could not find symbol `{symbol_name}` in {module.__name__}.")
-
-        _, offset = inspect.getsourcelines(symbol[-2])
-        if offset != 0:
-            offset -= 1
-        start += offset
-        end += offset
-
-    file = Path(inspect.getfile(module)).relative_to(PROJECT_ROOT).as_posix()
-
-    url = f"{SOURCE_FILE_LINK}/{file}#L{start}"
-    if end != start:
-        url += f"-L{end}"
-
-    return url
+linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK)