fork/mons

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

coloursofnoiseInline overlayfs help SEEALSO directivesa50fa59

fixes
2.0 KiB62 linesraw
1from docutils import nodes
2from sphinx.application import Sphinx
3from sphinx.builders import manpage as _manbuilder
4from sphinx.writers import manpage as _manwriter
5
6
7class BetterManPageTranslator(_manwriter.ManualPageTranslator):
8    _seealso_refs: list[nodes.Element] = []
9
10    def _append_seealso(self):
11        for ref in self._seealso_refs:
12            try:
13                self.body.append(self.visit_reference(ref))
14            except nodes.SkipNode:
15                pass
16            self.body.append(", ")
17        self.body.pop()
18        self.body.append("\n")
19
20    def visit_reference(self, node: nodes.Element) -> None:
21        refuri = node.get("refuri", "")
22        if refuri and "#" not in refuri:
23            self.body.append(refuri)
24            raise nodes.SkipNode
25        return super().visit_reference(node)
26
27    def visit_seealso(self, node: nodes.Element):
28        self._seealso_refs.append(node)
29        raise nodes.SkipNode
30
31    def visit_title(self, node: nodes.Element):
32        try:
33            super().visit_title(node)
34        except nodes.SkipNode as e:
35            raise e
36        finally:
37            if (
38                self.deunicode(node.astext().upper()) == "SEE ALSO"
39                and self._seealso_refs
40            ):
41                self._append_seealso()
42                self._seealso_refs.clear()
43
44    def depart_document(self, node: nodes.Element):
45        if self._seealso_refs:
46            self.body.append(".SH SEE ALSO\n.nh\n.sp\n")
47            self._append_seealso()
48            self._seealso_refs.clear()
49        super().depart_document(node)
50
51
52class ManBuilder(_manbuilder.ManualPageBuilder):
53    def get_target_uri(self, docname: str, typ=None) -> str:
54        for page in self.config.man_pages:
55            if docname == page[0]:
56                return f"{page[1]}({page[4]})"
57        return super().get_target_uri(docname, typ)
58
59
60def setup(app: Sphinx):
61    app.set_translator("man", BetterManPageTranslator, override=True)
62    app.add_builder(ManBuilder, override=True)