diff options
Diffstat (limited to 'docs/conf.py')
| -rw-r--r-- | docs/conf.py | 128 |
1 files changed, 23 insertions, 105 deletions
diff --git a/docs/conf.py b/docs/conf.py index 4ab831d3..e2801e2c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,16 +1,14 @@ # 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 sys -import typing from pathlib import Path import git import tomli -from sphinx.application import Sphinx + +from docs import utils # -- Project information ----------------------------------------------------- @@ -38,6 +36,7 @@ add_module_names = False # ones. extensions = [ "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", "sphinx.ext.autodoc", "sphinx.ext.todo", "sphinx.ext.napoleon", @@ -89,45 +88,6 @@ html_js_files = [ ] -# -- 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() - - def skip(*args) -> bool: """Things that should be skipped by the autodoc generation.""" name = args[2] @@ -140,11 +100,6 @@ def skip(*args) -> bool: return would_skip -def setup(app: Sphinx) -> None: - """Add extra hook-based autodoc configuration.""" - app.connect("autodoc-skip-member", skip) - - # -- Extension configuration ------------------------------------------------- # -- Options for todo extension ---------------------------------------------- @@ -169,60 +124,23 @@ extlinks = { } +# -- Options for intersphinx extension --------------------------------------- +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "discord": ("https://discordpy.readthedocs.io/en/master/", None), +} + + +# -- Options for the autodoc extension --------------------------------------- +utils.cleanup() +autodoc_default_options = { + "members": True, + "special-members": True, + "show-inheritance": True, + "imported-members": False, + "exclude-members": "__weakref__" +} + + # -- 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) |