diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog.rst | 3 | ||||
| -rw-r--r-- | docs/conf.py | 128 | ||||
| -rw-r--r-- | docs/utils.py | 117 |
3 files changed, 142 insertions, 106 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst index 743fcc20..25d01756 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,7 +4,8 @@ Changelog ========= - +- :release:`1.2.1 <22nd February 2022>` +- :support:`3` Added intersphinx to docs. - :release:`1.2.0 <9th January 2022>` - :feature:`12` Code block detection regex - :release:`1.1.0 <2nd December 2021>` 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) diff --git a/docs/utils.py b/docs/utils.py new file mode 100644 index 00000000..8bc69ccd --- /dev/null +++ b/docs/utils.py @@ -0,0 +1,117 @@ +"""Utilities used in generating docs.""" + +import ast +import importlib +import inspect +import typing +from pathlib import Path + +PROJECT_ROOT = Path(__file__).parent.parent + + +def linkcode_resolve(source_url: str, 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_url}/{file}#L{start}" + if end != start: + url += f"-L{end}" + + return url + + +def cleanup() -> None: + """Remove unneeded autogenerated doc files, and clean up others.""" + included = __get_included() + + for file in (PROJECT_ROOT / "docs" / "output").iterdir(): + if file.name in ("botcore.rst", "botcore.exts.rst") and file.name in included: + content = file.read_text(encoding="utf-8").splitlines(keepends=True) + + # Rename the extension to be less wordy + # Example: botcore.exts -> Botcore Exts + title = content[0].split()[0].strip().replace("botcore.", "").replace(".", " ").title() + title = f"{title}\n{'=' * len(title)}\n\n" + content[0:2] = title + + file.write_text("".join(content), encoding="utf-8") + + elif file.name in included: + # 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(keepends=True) + lines[0] = lines[0].replace("module", "").strip().split(".")[-1] + "\n" + file.write_text("".join(lines)) + + else: + # These are files that have not been explicitly included in the docs via __all__ + print("Deleted file", file.name) + file.unlink() + continue + + # Take the opportunity to configure autodoc + content = file.read_text(encoding="utf-8").replace("undoc-members", "special-members") + file.write_text(content, encoding="utf-8") + + +def __get_included() -> set[str]: + """Get a list of files that should be included in the final build.""" + + def get_all_from_module(module_name: str) -> set[str]: + module = importlib.import_module(module_name) + _modules = {module.__name__ + ".rst"} + + if hasattr(module, "__all__"): + for sub_module in module.__all__: + _modules.update(get_all_from_module(sub_module)) + + return _modules + + return get_all_from_module("botcore") |