diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 7811ccc5b..c9ae41609 100644 --- a/sphinx/writers/manpage.py +++ b/sphinx/writers/manpage.py @@ -9,9 +9,11 @@ """ import warnings -from typing import Iterable, cast +from typing import Any, Dict, Iterable +from typing import cast from docutils import nodes +from docutils.nodes import Element, Node, TextElement from docutils.writers.manpage import ( Writer, Translator as BaseTranslator @@ -26,21 +28,16 @@ from sphinx.util.docutils import SphinxTranslator from sphinx.util.i18n import format_date from sphinx.util.nodes import NodeMatcher -if False: - # For type annotation - from typing import Any, Dict # NOQA logger = logging.getLogger(__name__) class ManualPageWriter(Writer): - def __init__(self, builder): - # type: (Builder) -> None + def __init__(self, builder: Builder) -> None: super().__init__() self.builder = builder - def translate(self): - # type: () -> None + def translate(self) -> None: transform = NestedInlineTransform(self.document) transform.apply() visitor = self.builder.create_translator(self.document, self.builder) @@ -60,14 +57,12 @@ class NestedInlineTransform: foo=var &bar=2 """ - def __init__(self, document): - # type: (nodes.document) -> None + def __init__(self, document: nodes.document) -> None: self.document = document - def apply(self, **kwargs): - # type: (Any) -> None + def apply(self, **kwargs) -> None: matcher = NodeMatcher(nodes.literal, nodes.emphasis, nodes.strong) - for node in self.document.traverse(matcher): # type: nodes.TextElement + for node in self.document.traverse(matcher): # type: TextElement if any(matcher(subnode) for subnode in node): pos = node.parent.index(node) for subnode in reversed(node[1:]): @@ -86,8 +81,7 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): _docinfo = {} # type: Dict[str, Any] - def __init__(self, *args): - # type: (Any) -> None + def __init__(self, *args) -> None: if isinstance(args[0], nodes.document) and isinstance(args[1], Builder): document, builder = args else: @@ -126,153 +120,120 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): self.language.labels[label] = self.deunicode(translation) # type: ignore # overwritten -- added quotes around all .TH arguments - def header(self): - # type: () -> str + def header(self) -> str: tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\"" " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n" ".SH NAME\n" "%(title)s \\- %(subtitle)s\n") return tmpl % self._docinfo - def visit_start_of_file(self, node): - # type: (nodes.Element) -> None + def visit_start_of_file(self, node: Element) -> None: pass - def depart_start_of_file(self, node): - # type: (nodes.Element) -> None + def depart_start_of_file(self, node: Element) -> None: pass - def visit_desc(self, node): - # type: (nodes.Element) -> None + def visit_desc(self, node: Element) -> None: self.visit_definition_list(node) - def depart_desc(self, node): - # type: (nodes.Element) -> None + def depart_desc(self, node: Element) -> None: self.depart_definition_list(node) - def visit_desc_signature(self, node): - # type: (nodes.Element) -> None + def visit_desc_signature(self, node: Element) -> None: self.visit_definition_list_item(node) self.visit_term(node) - def depart_desc_signature(self, node): - # type: (nodes.Element) -> None + def depart_desc_signature(self, node: Element) -> None: self.depart_term(node) - def visit_desc_signature_line(self, node): - # type: (nodes.Element) -> None + def visit_desc_signature_line(self, node: Element) -> None: pass - def depart_desc_signature_line(self, node): - # type: (nodes.Element) -> None + def depart_desc_signature_line(self, node: Element) -> None: self.body.append(' ') - def visit_desc_addname(self, node): - # type: (nodes.Element) -> None + def visit_desc_addname(self, node: Element) -> None: pass - def depart_desc_addname(self, node): - # type: (nodes.Element) -> None + def depart_desc_addname(self, node: Element) -> None: pass - def visit_desc_type(self, node): - # type: (nodes.Element) -> None + def visit_desc_type(self, node: Element) -> None: pass - def depart_desc_type(self, node): - # type: (nodes.Element) -> None + def depart_desc_type(self, node: Element) -> None: pass - def visit_desc_returns(self, node): - # type: (nodes.Element) -> None + def visit_desc_returns(self, node: Element) -> None: self.body.append(' -> ') - def depart_desc_returns(self, node): - # type: (nodes.Element) -> None + def depart_desc_returns(self, node: Element) -> None: pass - def visit_desc_name(self, node): - # type: (nodes.Element) -> None + def visit_desc_name(self, node: Element) -> None: pass - def depart_desc_name(self, node): - # type: (nodes.Element) -> None + def depart_desc_name(self, node: Element) -> None: pass - def visit_desc_parameterlist(self, node): - # type: (nodes.Element) -> None + def visit_desc_parameterlist(self, node: Element) -> None: self.body.append('(') self.first_param = 1 - def depart_desc_parameterlist(self, node): - # type: (nodes.Element) -> None + def depart_desc_parameterlist(self, node: Element) -> None: self.body.append(')') - def visit_desc_parameter(self, node): - # type: (nodes.Element) -> None + def visit_desc_parameter(self, node: Element) -> None: if not self.first_param: self.body.append(', ') else: self.first_param = 0 - def depart_desc_parameter(self, node): - # type: (nodes.Element) -> None + def depart_desc_parameter(self, node: Element) -> None: pass - def visit_desc_optional(self, node): - # type: (nodes.Element) -> None + def visit_desc_optional(self, node: Element) -> None: self.body.append('[') - def depart_desc_optional(self, node): - # type: (nodes.Element) -> None + def depart_desc_optional(self, node: Element) -> None: self.body.append(']') - def visit_desc_annotation(self, node): - # type: (nodes.Element) -> None + def visit_desc_annotation(self, node: Element) -> None: pass - def depart_desc_annotation(self, node): - # type: (nodes.Element) -> None + def depart_desc_annotation(self, node: Element) -> None: pass - def visit_desc_content(self, node): - # type: (nodes.Element) -> None + def visit_desc_content(self, node: Element) -> None: self.visit_definition(node) - def depart_desc_content(self, node): - # type: (nodes.Element) -> None + def depart_desc_content(self, node: Element) -> None: self.depart_definition(node) - def visit_versionmodified(self, node): - # type: (nodes.Element) -> None + def visit_versionmodified(self, node: Element) -> None: self.visit_paragraph(node) - def depart_versionmodified(self, node): - # type: (nodes.Element) -> None + def depart_versionmodified(self, node: Element) -> None: self.depart_paragraph(node) # overwritten -- don't make whole of term bold if it includes strong node - def visit_term(self, node): - # type: (nodes.Element) -> None + def visit_term(self, node: Element) -> None: if node.traverse(nodes.strong): self.body.append('\n') else: super().visit_term(node) # overwritten -- we don't want source comments to show up - def visit_comment(self, node): # type: ignore - # type: (nodes.Element) -> None + def visit_comment(self, node: Element) -> None: # type: ignore raise nodes.SkipNode # overwritten -- added ensure_eol() - def visit_footnote(self, node): - # type: (nodes.Element) -> None + def visit_footnote(self, node: Element) -> None: self.ensure_eol() super().visit_footnote(node) # overwritten -- handle footnotes rubric - def visit_rubric(self, node): - # type: (nodes.Element) -> None + def visit_rubric(self, node: Element) -> None: self.ensure_eol() if len(node) == 1 and node.astext() in ('Footnotes', _('Footnotes')): self.body.append('.SH ' + self.deunicode(node.astext()).upper() + '\n') @@ -280,20 +241,16 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): else: self.body.append('.sp\n') - def depart_rubric(self, node): - # type: (nodes.Element) -> None + def depart_rubric(self, node: Element) -> None: self.body.append('\n') - def visit_seealso(self, node): - # type: (nodes.Element) -> None + def visit_seealso(self, node: Element) -> None: self.visit_admonition(node, 'seealso') - def depart_seealso(self, node): - # type: (nodes.Element) -> None + def depart_seealso(self, node: Element) -> None: self.depart_admonition(node) - def visit_productionlist(self, node): - # type: (nodes.Element) -> None + def visit_productionlist(self, node: Element) -> None: self.ensure_eol() names = [] self.in_productionlist += 1 @@ -318,25 +275,21 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): self.in_productionlist -= 1 raise nodes.SkipNode - def visit_production(self, node): - # type: (nodes.Element) -> None + def visit_production(self, node: Element) -> None: pass - def depart_production(self, node): - # type: (nodes.Element) -> None + def depart_production(self, node: Element) -> None: pass # overwritten -- don't emit a warning for images - def visit_image(self, node): - # type: (nodes.Element) -> None + def visit_image(self, node: Element) -> None: if 'alt' in node.attributes: self.body.append(_('[image: %s]') % node['alt'] + '\n') self.body.append(_('[image]') + '\n') raise nodes.SkipNode # overwritten -- don't visit inner marked up nodes - def visit_reference(self, node): - # type: (nodes.Element) -> None + def visit_reference(self, node: Element) -> None: self.body.append(self.defs['reference'][0]) # avoid repeating escaping code... fine since # visit_Text calls astext() and only works on that afterwards @@ -357,59 +310,46 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): '>']) raise nodes.SkipNode - def visit_number_reference(self, node): - # type: (nodes.Element) -> None + def visit_number_reference(self, node: Element) -> None: text = nodes.Text(node.get('title', '#')) self.visit_Text(text) raise nodes.SkipNode - def visit_centered(self, node): - # type: (nodes.Element) -> None + def visit_centered(self, node: Element) -> None: self.ensure_eol() self.body.append('.sp\n.ce\n') - def depart_centered(self, node): - # type: (nodes.Element) -> None + def depart_centered(self, node: Element) -> None: self.body.append('\n.ce 0\n') - def visit_compact_paragraph(self, node): - # type: (nodes.Element) -> None + def visit_compact_paragraph(self, node: Element) -> None: pass - def depart_compact_paragraph(self, node): - # type: (nodes.Element) -> None + def depart_compact_paragraph(self, node: Element) -> None: pass - def visit_download_reference(self, node): - # type: (nodes.Element) -> None + def visit_download_reference(self, node: Element) -> None: pass - def depart_download_reference(self, node): - # type: (nodes.Element) -> None + def depart_download_reference(self, node: Element) -> None: pass - def visit_toctree(self, node): - # type: (nodes.Element) -> None + def visit_toctree(self, node: Element) -> None: raise nodes.SkipNode - def visit_index(self, node): - # type: (nodes.Element) -> None + def visit_index(self, node: Element) -> None: raise nodes.SkipNode - def visit_tabular_col_spec(self, node): - # type: (nodes.Element) -> None + def visit_tabular_col_spec(self, node: Element) -> None: raise nodes.SkipNode - def visit_glossary(self, node): - # type: (nodes.Element) -> None + def visit_glossary(self, node: Element) -> None: pass - def depart_glossary(self, node): - # type: (nodes.Element) -> None + def depart_glossary(self, node: Element) -> None: pass - def visit_acks(self, node): - # type: (nodes.Element) -> None + def visit_acks(self, node: Element) -> None: bullet_list = cast(nodes.bullet_list, node[0]) list_items = cast(Iterable[nodes.list_item], bullet_list) self.ensure_eol() @@ -419,72 +359,57 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): self.body.append('\n') raise nodes.SkipNode - def visit_hlist(self, node): - # type: (nodes.Element) -> None + def visit_hlist(self, node: Element) -> None: self.visit_bullet_list(node) - def depart_hlist(self, node): - # type: (nodes.Element) -> None + def depart_hlist(self, node: Element) -> None: self.depart_bullet_list(node) - def visit_hlistcol(self, node): - # type: (nodes.Element) -> None + def visit_hlistcol(self, node: Element) -> None: pass - def depart_hlistcol(self, node): - # type: (nodes.Element) -> None + def depart_hlistcol(self, node: Element) -> None: pass - def visit_literal_emphasis(self, node): - # type: (nodes.Element) -> None + def visit_literal_emphasis(self, node: Element) -> None: return self.visit_emphasis(node) - def depart_literal_emphasis(self, node): - # type: (nodes.Element) -> None + def depart_literal_emphasis(self, node: Element) -> None: return self.depart_emphasis(node) - def visit_literal_strong(self, node): - # type: (nodes.Element) -> None + def visit_literal_strong(self, node: Element) -> None: return self.visit_strong(node) - def depart_literal_strong(self, node): - # type: (nodes.Element) -> None + def depart_literal_strong(self, node: Element) -> None: return self.depart_strong(node) - def visit_abbreviation(self, node): - # type: (nodes.Element) -> None + def visit_abbreviation(self, node: Element) -> None: pass - def depart_abbreviation(self, node): - # type: (nodes.Element) -> None + def depart_abbreviation(self, node: Element) -> None: pass - def visit_manpage(self, node): - # type: (nodes.Element) -> None + def visit_manpage(self, node: Element) -> None: return self.visit_strong(node) - def depart_manpage(self, node): - # type: (nodes.Element) -> None + def depart_manpage(self, node: Element) -> None: return self.depart_strong(node) # overwritten: handle section titles better than in 0.6 release - def visit_caption(self, node): - # type: (nodes.Element) -> None + def visit_caption(self, node: Element) -> None: if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'): self.body.append('.sp\n') else: super().visit_caption(node) - def depart_caption(self, node): - # type: (nodes.Element) -> None + def depart_caption(self, node: Element) -> None: if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'): self.body.append('\n') else: super().depart_caption(node) # overwritten: handle section titles better than in 0.6 release - def visit_title(self, node): - # type: (nodes.Element) -> None + def visit_title(self, node: Element) -> None: if isinstance(node.parent, addnodes.seealso): self.body.append('.IP "') return @@ -498,47 +423,37 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator): raise nodes.SkipNode return super().visit_title(node) - def depart_title(self, node): - # type: (nodes.Element) -> None + def depart_title(self, node: Element) -> None: if isinstance(node.parent, addnodes.seealso): self.body.append('"\n') return return super().depart_title(node) - def visit_raw(self, node): - # type: (nodes.Element) -> None + def visit_raw(self, node: Element) -> None: if 'manpage' in node.get('format', '').split(): self.body.append(node.astext()) raise nodes.SkipNode - def visit_meta(self, node): - # type: (nodes.Element) -> None + def visit_meta(self, node: Element) -> None: raise nodes.SkipNode - def visit_inline(self, node): - # type: (nodes.Element) -> None + def visit_inline(self, node: Element) -> None: pass - def depart_inline(self, node): - # type: (nodes.Element) -> None + def depart_inline(self, node: Element) -> None: pass - def visit_math(self, node): - # type: (nodes.Element) -> None + def visit_math(self, node: Element) -> None: pass - def depart_math(self, node): - # type: (nodes.Element) -> None + def depart_math(self, node: Element) -> None: pass - def visit_math_block(self, node): - # type: (nodes.Element) -> None + def visit_math_block(self, node: Element) -> None: self.visit_centered(node) - def depart_math_block(self, node): - # type: (nodes.Element) -> None + def depart_math_block(self, node: Element) -> None: self.depart_centered(node) - def unknown_visit(self, node): - # type: (nodes.Node) -> None + def unknown_visit(self, node: Node) -> None: raise NotImplementedError('Unknown node: ' + node.__class__.__name__)