fork/mons

git clone https://git.julia.blue/fork/mons

coloursofnoiseUpdate pre-commit hooks, include docs in auto-formatting17b9303

misc-fixes
4.8 KiB155 linesraw
1import copy
2
3from docutils.parsers.rst import directives
4from sphinx.application import Sphinx
5from sphinx.domains.python import PyAttribute
6from sphinx.ext import autodoc
7
8
9class ClassMembersDocumenter(autodoc.ClassDocumenter):
10    option_spec = {
11        **autodoc.ClassDocumenter.option_spec,
12        "skip_docstr": directives.unchanged,
13    }
14    objtype = "classmembers"
15
16    def generate(self, *args, **kwargs) -> None:
17        self.options["members"] = autodoc.ALL
18        self.is_toplevel = not self.options.get("classmembersdocumenter", False)
19        self.options["classmembersdocumenter"] = True
20        self.doc_as_attr = False
21
22        super().generate(*args, **kwargs)
23
24        if not self.is_toplevel:
25            return
26
27        result_strlist = self.directive.result
28
29        result_strlist.trim_start(4)
30        result_strlist.trim_left(3)
31
32        s_drop = list()
33        current_prefix = ""
34        for i in range(len(result_strlist)):
35            s: str = result_strlist[i]
36
37            if ".. py:classmembers::" in s:
38                current_prefix = s.split()[-1] + "."
39
40            if ":value:" in s:
41                s_drop.append(s)
42                continue
43
44            if ":type:" in s and "~typing.Optional" in s:
45                result_strlist[i] = s.replace("~typing.Optional[", "")[:-1]
46
47            if ".. py:classmembersattribute::" in s:
48                directive, arguments = s.rstrip().split("::", maxsplit=1)
49                result_strlist[i] = (
50                    directive + ":: " + current_prefix + arguments.split(".")[-1]
51                )
52
53        for s in s_drop:
54            result_strlist.remove(s)
55
56    def document_members(self, all_members: bool = False):
57        objpath = self.objpath
58        if not self.object.__init__.__qualname__.startswith(self.object.__qualname__):
59            self.objpath = self.object.__init__.__qualname__.split(".")[:-1]
60
61        super().document_members(all_members)
62
63        self.objpath = objpath
64
65    def add_content(self, more_content) -> None:
66        skip_docstr = self.options.get("skip_docstr", None)
67        if skip_docstr and not (skip_docstr == "all" or self.is_toplevel):
68            super().add_content(more_content)
69
70    def get_object_members(self, want_all: bool) -> tuple[bool, autodoc.ObjectMembers]:
71        t_del = list()
72        for n, m in self.object.__dict__.items():
73            t = type(m)
74            if getattr(self.object, t.__name__, None) == t:
75                t_del.append(t.__name__)
76                t = copy.copy(t)
77                t.__qualname__ = t.__qualname__.replace(t.__name__, n)
78                t.__name__ = n
79                setattr(self.object, n, t)
80
81        ret, members = super().get_object_members(want_all)
82
83        members = [(n, m) for n, m in members if n not in t_del]
84        return ret, members
85
86    def format_signature(self, **kwargs) -> str:
87        return ""
88
89
90class ClassMembersAttributeDocumenter(autodoc.AttributeDocumenter):
91    objtype = "classmembersattribute"
92
93    def generate(self, *args, **kwargs) -> None:
94        super().generate(*args, **kwargs)
95
96    def import_object(self, raiseerror: bool = False) -> bool:
97        ret = super().import_object(raiseerror)
98        self.parent.__qualname__ = ".".join(self.objpath[:-1])
99        return ret
100
101
102class PyClassMember(PyAttribute):
103    def get_signatures(self):
104        return [sig.split(".")[-1] for sig in super().get_signatures()]
105
106
107class ClassMembersDirective(PyClassMember):
108    option_spec = {**PyAttribute.option_spec, "toplevel": directives.unchanged}
109    allow_nesting = True
110
111
112class AutoDocstr(
113    autodoc.ClassLevelDocumenter,
114    autodoc.ModuleLevelDocumenter,
115    autodoc.ModuleDocumenter,
116):
117    objtype = "docstr"
118    content_indent = ""
119
120    @classmethod
121    def can_document_member(cls, *args, **kwargs):
122        return False
123
124    def add_line(self, *args, **kwargs) -> None:
125        self.indent = ""
126        return super().add_line(*args, **kwargs)
127
128    def resolve_name(self, *args, **kwargs):
129        module, name = autodoc.ClassLevelDocumenter.resolve_name(self, *args, **kwargs)
130
131        if not module:
132            module, name = autodoc.ModuleLevelDocumenter.resolve_name(
133                self, *args, **kwargs
134            )
135
136        if not module:
137            module, name = autodoc.ClassLevelDocumenter.resolve_name(
138                self, *args, **kwargs
139            )
140
141        return module, name
142
143    def document_members(self, all_members: bool = False) -> None:
144        pass  # skip
145
146    def add_directive_header(self, sig: str) -> None:
147        pass  # skip
148
149
150def setup(app: Sphinx):
151    app.add_autodocumenter(AutoDocstr)
152    app.add_autodocumenter(ClassMembersDocumenter)
153    app.add_autodocumenter(ClassMembersAttributeDocumenter)
154    app.add_directive_to_domain("py", "classmembers", ClassMembersDirective)
155    app.add_directive_to_domain("py", "classmembersattribute", PyClassMember)