1
Fork 0
mirror of https://github.com/RGBCube/GitHubWrapper synced 2025-06-30 03:32:12 +00:00

Cleaned up docs/

- Linted
- Changed Github-Api-Wrapper to GitHub-API-Wrapper
This commit is contained in:
RGBCube 2022-06-25 14:07:43 +03:00
parent a33985c69b
commit f6b9852167
10 changed files with 219 additions and 174 deletions

View file

@ -42,51 +42,51 @@ class attributetable_item(nodes.Part, nodes.Element):
def visit_attributetable_node(self: DPYHTML5Translator, node: attributetable) -> None:
class_ = node['python-class']
class_ = node["python-class"]
self.body.append(f'<div class="py-attribute-table" data-move-to-id="{class_}">')
def visit_attributetablecolumn_node(self: DPYHTML5Translator, node: attributetablecolumn) -> None:
self.body.append(self.starttag(node, 'div', CLASS='py-attribute-table-column'))
self.body.append(self.starttag(node, "div", CLASS="py-attribute-table-column"))
def visit_attributetabletitle_node(self: DPYHTML5Translator, node: attributetabletitle) -> None:
self.body.append(self.starttag(node, 'span'))
self.body.append(self.starttag(node, "span"))
def visit_attributetablebadge_node(self: DPYHTML5Translator, node: attributetablebadge) -> None:
attributes = {
'class': 'py-attribute-table-badge',
'title': node['badge-type'],
"class": "py-attribute-table-badge",
"title": node["badge-type"],
}
self.body.append(self.starttag(node, 'span', **attributes))
self.body.append(self.starttag(node, "span", **attributes))
def visit_attributetable_item_node(self: DPYHTML5Translator, node: attributetable_item) -> None:
self.body.append(self.starttag(node, 'li', CLASS='py-attribute-table-entry'))
self.body.append(self.starttag(node, "li", CLASS="py-attribute-table-entry"))
def depart_attributetable_node(self: DPYHTML5Translator, node: attributetable) -> None:
self.body.append('</div>')
self.body.append("</div>")
def depart_attributetablecolumn_node(self: DPYHTML5Translator, node: attributetablecolumn) -> None:
self.body.append('</div>')
self.body.append("</div>")
def depart_attributetabletitle_node(self: DPYHTML5Translator, node: attributetabletitle) -> None:
self.body.append('</span>')
self.body.append("</span>")
def depart_attributetablebadge_node(self: DPYHTML5Translator, node: attributetablebadge) -> None:
self.body.append('</span>')
self.body.append("</span>")
def depart_attributetable_item_node(self: DPYHTML5Translator, node: attributetable_item) -> None:
self.body.append('</li>')
self.body.append("</li>")
_name_parser_regex = re.compile(r'(?P<module>[\w.]+\.)?(?P<name>\w+)')
_name_parser_regex = re.compile(r"(?P<module>[\w.]+\.)?(?P<name>\w+)")
class PyAttributeTable(SphinxDirective):
@ -99,16 +99,18 @@ class PyAttributeTable(SphinxDirective):
def parse_name(self, content: str) -> Tuple[str, str]:
match = _name_parser_regex.match(content)
if match is None:
raise RuntimeError(f"content {content} somehow doesn't match regex in {self.env.docname}.")
raise RuntimeError(
f"content {content} somehow doesn't match regex in {self.env.docname}."
)
path, name = match.groups()
if path:
modulename = path.rstrip('.')
modulename = path.rstrip(".")
else:
modulename = self.env.temp_data.get('autodoc:module')
modulename = self.env.temp_data.get("autodoc:module")
if not modulename:
modulename = self.env.ref_context.get('py:module')
modulename = self.env.ref_context.get("py:module")
if modulename is None:
raise RuntimeError(f'modulename somehow None for {content} in {self.env.docname}.')
raise RuntimeError(f"modulename somehow None for {content} in {self.env.docname}.")
return modulename, name
@ -140,12 +142,12 @@ class PyAttributeTable(SphinxDirective):
replaced.
"""
content = self.arguments[0].strip()
node = attributetableplaceholder('')
node = attributetableplaceholder("")
modulename, name = self.parse_name(content)
node['python-doc'] = self.env.docname
node['python-module'] = modulename
node['python-class'] = name
node['python-full-name'] = f'{modulename}.{name}'
node["python-doc"] = self.env.docname
node["python-module"] = modulename
node["python-class"] = name
node["python-full-name"] = f"{modulename}.{name}"
return [node]
@ -153,20 +155,20 @@ def build_lookup_table(env: Optional[BuildEnvironment]) -> Dict[str, List[str]]:
# Given an environment, load up a lookup table of
# full-class-name: objects
result = {}
domain = env.domains['py'] # type: ignore
domain = env.domains["py"] # type: ignore
ignored = {
'data',
'exception',
'module',
'class',
"data",
"exception",
"module",
"class",
}
for fullname, _, objtype, docname, _, _ in domain.get_objects():
if objtype in ignored:
continue
classname, _, child = fullname.rpartition('.')
classname, _, child = fullname.rpartition(".")
try:
result[classname].append(child)
except KeyError:
@ -186,15 +188,19 @@ def process_attributetable(app: Sphinx, doctree: nodes.Node, fromdocname: str) -
lookup = build_lookup_table(env)
for node in doctree.traverse(attributetableplaceholder):
modulename, classname, fullname = node['python-module'], node['python-class'], node['python-full-name']
modulename, classname, fullname = (
node["python-module"],
node["python-class"],
node["python-full-name"],
)
groups = get_class_results(lookup, modulename, classname, fullname)
table = attributetable('')
table = attributetable("")
for label, subitems in groups.items():
if not subitems:
continue
table.append(class_results_to_node(label, sorted(subitems, key=lambda c: c.label)))
table['python-class'] = fullname
table["python-class"] = fullname
if not table:
node.replace_self([])
@ -209,8 +215,8 @@ def get_class_results(
cls = getattr(module, name)
groups: Dict[str, List[TableElement]] = {
_('Attributes'): [],
_('Methods'): [],
_("Attributes"): [],
_("Methods"): [],
}
try:
@ -219,8 +225,8 @@ def get_class_results(
return groups
for attr in members:
attrlookup = f'{fullname}.{attr}'
key = _('Attributes')
attrlookup = f"{fullname}.{attr}"
key = _("Attributes")
badge = None
label = attr
value = None
@ -231,30 +237,30 @@ def get_class_results(
break
if value is not None:
doc = value.__doc__ or ''
if inspect.iscoroutinefunction(value) or doc.startswith('|coro|'):
key = _('Methods')
badge = attributetablebadge('async', 'async')
badge['badge-type'] = _('coroutine')
doc = value.__doc__ or ""
if inspect.iscoroutinefunction(value) or doc.startswith("|coro|"):
key = _("Methods")
badge = attributetablebadge("async", "async")
badge["badge-type"] = _("coroutine")
elif isinstance(value, classmethod):
key = _('Methods')
label = f'{name}.{attr}'
badge = attributetablebadge('cls', 'cls')
badge['badge-type'] = _('classmethod')
key = _("Methods")
label = f"{name}.{attr}"
badge = attributetablebadge("cls", "cls")
badge["badge-type"] = _("classmethod")
elif inspect.isfunction(value):
if doc.startswith(('A decorator', 'A shortcut decorator')):
if doc.startswith(("A decorator", "A shortcut decorator")):
# finicky but surprisingly consistent
key = _('Methods')
badge = attributetablebadge('@', '@')
badge['badge-type'] = _('decorator')
key = _("Methods")
badge = attributetablebadge("@", "@")
badge["badge-type"] = _("decorator")
elif inspect.isasyncgenfunction(value):
key = _('Methods')
badge = attributetablebadge('async for', 'async for')
badge['badge-type'] = _('async iterable')
key = _("Methods")
badge = attributetablebadge("async for", "async for")
badge["badge-type"] = _("async iterable")
else:
key = _('Methods')
badge = attributetablebadge('def', 'def')
badge['badge-type'] = _('method')
key = _("Methods")
badge = attributetablebadge("def", "def")
badge["badge-type"] = _("method")
groups[key].append(TableElement(fullname=attrlookup, label=label, badge=badge))
@ -263,26 +269,40 @@ def get_class_results(
def class_results_to_node(key: str, elements: Sequence[TableElement]) -> attributetablecolumn:
title = attributetabletitle(key, key)
ul = nodes.bullet_list('')
ul = nodes.bullet_list("")
for element in elements:
ref = nodes.reference(
'', '', internal=True, refuri=f'#{element.fullname}', anchorname='', *[nodes.Text(element.label)]
"",
"",
internal=True,
refuri=f"#{element.fullname}",
anchorname="",
*[nodes.Text(element.label)],
)
para = addnodes.compact_paragraph('', '', ref)
para = addnodes.compact_paragraph("", "", ref)
if element.badge is not None:
ul.append(attributetable_item('', element.badge, para))
ul.append(attributetable_item("", element.badge, para))
else:
ul.append(attributetable_item('', para))
ul.append(attributetable_item("", para))
return attributetablecolumn('', title, ul)
return attributetablecolumn("", title, ul)
def setup(app: Sphinx) -> None:
app.add_directive('attributetable', PyAttributeTable)
app.add_directive("attributetable", PyAttributeTable)
app.add_node(attributetable, html=(visit_attributetable_node, depart_attributetable_node))
app.add_node(attributetablecolumn, html=(visit_attributetablecolumn_node, depart_attributetablecolumn_node))
app.add_node(attributetabletitle, html=(visit_attributetabletitle_node, depart_attributetabletitle_node))
app.add_node(attributetablebadge, html=(visit_attributetablebadge_node, depart_attributetablebadge_node))
app.add_node(attributetable_item, html=(visit_attributetable_item_node, depart_attributetable_item_node))
app.add_node(
attributetablecolumn,
html=(visit_attributetablecolumn_node, depart_attributetablecolumn_node),
)
app.add_node(
attributetabletitle, html=(visit_attributetabletitle_node, depart_attributetabletitle_node)
)
app.add_node(
attributetablebadge, html=(visit_attributetablebadge_node, depart_attributetablebadge_node)
)
app.add_node(
attributetable_item, html=(visit_attributetable_item_node, depart_attributetable_item_node)
)
app.add_node(attributetableplaceholder)
app.connect('doctree-resolved', process_attributetable)
app.connect("doctree-resolved", process_attributetable)

View file

@ -6,11 +6,11 @@ from sphinx.writers.html5 import HTML5Translator
class DPYHTML5Translator(HTML5Translator):
def visit_section(self, node):
self.section_level += 1
self.body.append(self.starttag(node, 'section'))
self.body.append(self.starttag(node, "section"))
def depart_section(self, node):
self.section_level -= 1
self.body.append('</section>\n')
self.body.append("</section>\n")
def visit_table(self, node):
self.body.append('<div class="table-wrapper">')
@ -18,7 +18,7 @@ class DPYHTML5Translator(HTML5Translator):
def depart_table(self, node):
super().depart_table(node)
self.body.append('</div>')
self.body.append("</div>")
class DPYStandaloneHTMLBuilder(StandaloneHTMLBuilder):
@ -32,45 +32,46 @@ class DPYStandaloneHTMLBuilder(StandaloneHTMLBuilder):
indexcounts.append(sum(1 + len(subitems) for _, (_, subitems, _) in entries))
genindexcontext = {
'genindexentries': genindex,
'genindexcounts': indexcounts,
'split_index': self.config.html_split_index,
"genindexentries": genindex,
"genindexcounts": indexcounts,
"split_index": self.config.html_split_index,
}
if self.config.html_split_index:
self.handle_page('genindex', genindexcontext, 'genindex-split.html')
self.handle_page('genindex-all', genindexcontext, 'genindex.html')
self.handle_page("genindex", genindexcontext, "genindex-split.html")
self.handle_page("genindex-all", genindexcontext, "genindex.html")
for (key, entries), count in zip(genindex, indexcounts):
ctx = {'key': key, 'entries': entries, 'count': count, 'genindexentries': genindex}
self.handle_page(f"genindex-{key}", ctx, 'genindex-single.html')
ctx = {"key": key, "entries": entries, "count": count, "genindexentries": genindex}
self.handle_page(f"genindex-{key}", ctx, "genindex-single.html")
else:
self.handle_page('genindex', genindexcontext, 'genindex.html')
self.handle_page("genindex", genindexcontext, "genindex.html")
def add_custom_jinja2(app):
env = app.builder.templates.environment
env.tests['prefixedwith'] = str.startswith
env.tests['suffixedwith'] = str.endswith
env.tests["prefixedwith"] = str.startswith
env.tests["suffixedwith"] = str.endswith
def add_builders(app):
"""This is necessary because RTD injects their own for some reason."""
app.set_translator('html', DPYHTML5Translator, override=True)
app.set_translator("html", DPYHTML5Translator, override=True)
app.add_builder(DPYStandaloneHTMLBuilder, override=True)
try:
original = app.registry.builders['readthedocs']
original = app.registry.builders["readthedocs"]
except KeyError:
pass
else:
injected_mro = tuple(
base if base is not StandaloneHTMLBuilder else DPYStandaloneHTMLBuilder for base in original.mro()[1:]
base if base is not StandaloneHTMLBuilder else DPYStandaloneHTMLBuilder
for base in original.mro()[1:]
)
new_builder = type(original.__name__, injected_mro, {'name': 'readthedocs'})
app.set_translator('readthedocs', DPYHTML5Translator, override=True)
new_builder = type(original.__name__, injected_mro, {"name": "readthedocs"})
app.set_translator("readthedocs", DPYHTML5Translator, override=True)
app.add_builder(new_builder, override=True)
def setup(app):
add_builders(app)
app.connect('builder-inited', add_custom_jinja2)
app.connect("builder-inited", add_custom_jinja2)

View file

@ -13,20 +13,20 @@ class summary(nodes.General, nodes.Element):
def visit_details_node(self, node):
self.body.append(self.starttag(node, 'details', CLASS=node.attributes.get('class', '')))
self.body.append(self.starttag(node, "details", CLASS=node.attributes.get("class", "")))
def visit_summary_node(self, node):
self.body.append(self.starttag(node, 'summary', CLASS=node.attributes.get('summary-class', '')))
self.body.append(self.starttag(node, "summary", CLASS=node.attributes.get("summary-class", "")))
self.body.append(node.rawsource)
def depart_details_node(self, node):
self.body.append('</details>\n')
self.body.append("</details>\n")
def depart_summary_node(self, node):
self.body.append('</summary>')
self.body.append("</summary>")
class DetailsDirective(Directive):
@ -34,8 +34,8 @@ class DetailsDirective(Directive):
optional_arguments = 1
option_spec = {
'class': directives.class_option,
'summary-class': directives.class_option,
"class": directives.class_option,
"summary-class": directives.class_option,
}
has_content = True
@ -44,12 +44,14 @@ class DetailsDirective(Directive):
set_classes(self.options)
self.assert_has_content()
text = '\n'.join(self.content)
text = "\n".join(self.content)
node = details(text, **self.options)
if self.arguments:
summary_node = summary(self.arguments[0], **self.options)
summary_node.source, summary_node.line = self.state_machine.get_source_and_line(self.lineno)
summary_node.source, summary_node.line = self.state_machine.get_source_and_line(
self.lineno
)
node += summary_node
self.state.nested_parse(self.content, self.content_offset, node)
@ -59,4 +61,4 @@ class DetailsDirective(Directive):
def setup(app):
app.add_node(details, html=(visit_details_node, depart_details_node))
app.add_node(summary, html=(visit_summary_node, depart_summary_node))
app.add_directive('details', DetailsDirective)
app.add_directive("details", DetailsDirective)

View file

@ -7,11 +7,11 @@ class exception_hierarchy(nodes.General, nodes.Element):
def visit_exception_hierarchy_node(self, node):
self.body.append(self.starttag(node, 'div', CLASS='exception-hierarchy-content'))
self.body.append(self.starttag(node, "div", CLASS="exception-hierarchy-content"))
def depart_exception_hierarchy_node(self, node):
self.body.append('</div>\n')
self.body.append("</div>\n")
class ExceptionHierarchyDirective(Directive):
@ -19,11 +19,13 @@ class ExceptionHierarchyDirective(Directive):
def run(self):
self.assert_has_content()
node = exception_hierarchy('\n'.join(self.content))
node = exception_hierarchy("\n".join(self.content))
self.state.nested_parse(self.content, self.content_offset, node)
return [node]
def setup(app):
app.add_node(exception_hierarchy, html=(visit_exception_hierarchy_node, depart_exception_hierarchy_node))
app.add_directive('exception_hierarchy', ExceptionHierarchyDirective)
app.add_node(
exception_hierarchy, html=(visit_exception_hierarchy_node, depart_exception_hierarchy_node)
)
app.add_directive("exception_hierarchy", ExceptionHierarchyDirective)

View file

@ -10,12 +10,12 @@ class NitpickFileIgnorer(logging.Filter):
super().__init__()
def filter(self, record: sphinx_logging.SphinxLogRecord) -> bool:
if getattr(record, 'type', None) == 'ref':
return record.location.get('refdoc') not in self.app.config.nitpick_ignore_files
if getattr(record, "type", None) == "ref":
return record.location.get("refdoc") not in self.app.config.nitpick_ignore_files
return True
def setup(app: Sphinx):
app.add_config_value('nitpick_ignore_files', [], '')
app.add_config_value("nitpick_ignore_files", [], "")
f = NitpickFileIgnorer(app)
sphinx_logging.getLogger('sphinx.transforms.post_transforms').logger.addFilter(f)
sphinx_logging.getLogger("sphinx.transforms.post_transforms").logger.addFilter(f)

View file

@ -15,7 +15,13 @@ from sphinx.util.typing import RoleFunction
def make_link_role(resource_links: Dict[str, str]) -> RoleFunction:
def role(
typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: Dict = {}, content: List[str] = []
typ: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict = {},
content: List[str] = [],
) -> Tuple[List[Node], List[system_message]]:
text = utils.unescape(text)
@ -30,10 +36,10 @@ def make_link_role(resource_links: Dict[str, str]) -> RoleFunction:
def add_link_role(app: Sphinx) -> None:
app.add_role('resource', make_link_role(app.config.resource_links))
app.add_role("resource", make_link_role(app.config.resource_links))
def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('resource_links', {}, 'env')
app.connect('builder-inited', add_link_role)
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
app.add_config_value("resource_links", {}, "env")
app.connect("builder-inited", add_link_role)
return {"version": sphinx.__display_version__, "parallel_read_safe": True}