""" sphinx.writers.texinfo ~~~~~~~~~~~~~~~~~~~~~~ Custom docutils writer for Texinfo. :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ import re import textwrap import warnings from os import path from typing import (Any, Dict, Iterable, Iterator, List, Optional, Pattern, Set, Tuple, Union, cast) from docutils import nodes, writers from docutils.nodes import Element, Node, Text from sphinx import __display_version__, addnodes from sphinx.deprecation import RemovedInSphinx50Warning from sphinx.domains import IndexEntry from sphinx.domains.index import IndexDomain from sphinx.errors import ExtensionError from sphinx.locale import _, __, admonitionlabels from sphinx.util import logging from sphinx.util.docutils import SphinxTranslator from sphinx.util.i18n import format_date from sphinx.writers.latex import collected_footnote if False: # For type annotation from sphinx.builders.texinfo import TexinfoBuilder logger = logging.getLogger(__name__) COPYING = """\ @quotation %(project)s %(release)s, %(date)s %(author)s Copyright @copyright{} %(copyright)s @end quotation """ TEMPLATE = """\ \\input texinfo @c -*-texinfo-*- @c %%**start of header @setfilename %(filename)s @documentencoding UTF-8 @ifinfo @*Generated by Sphinx """ + __display_version__ + """.@* @end ifinfo @settitle %(title)s @defindex ge @paragraphindent %(paragraphindent)s @exampleindent %(exampleindent)s @finalout %(direntry)s @definfoenclose strong,`,' @definfoenclose emph,`,' @c %%**end of header @copying %(copying)s @end copying @titlepage @title %(title)s @insertcopying @end titlepage @contents @c %%** start of user preamble %(preamble)s @c %%** end of user preamble @ifnottex @node Top @top %(title)s @insertcopying @end ifnottex @c %%**start of body %(body)s @c %%**end of body @bye """ def find_subsections(section: Element) -> List[nodes.section]: """Return a list of subsections for the given ``section``.""" result = [] for child in section: if isinstance(child, nodes.section): result.append(child) continue elif isinstance(child, nodes.Element): result.extend(find_subsections(child)) return result def smart_capwords(s: str, sep: str = None) -> str: """Like string.capwords() but does not capitalize words that already contain a capital letter.""" words = s.split(sep) for i, word in enumerate(words): if all(x.islower() for x in word): words[i] = word.capitalize() return (sep or ' ').join(words) class TexinfoWriter(writers.Writer): """Texinfo writer for generating Texinfo documents.""" supported = ('texinfo', 'texi') settings_spec = ( 'Texinfo Specific Options', None, ( ("Name of the Info file", ['--texinfo-filename'], {'default': ''}), ('Dir entry', ['--texinfo-dir-entry'], {'default': ''}), ('Description', ['--texinfo-dir-description'], {'default': ''}), ('Category', ['--texinfo-dir-category'], {'default': 'Miscellaneous'}))) # type: Tuple[str, Any, Tuple[Tuple[str, List[str], Dict[str, str]], ...]] # NOQA settings_defaults = {} # type: Dict output = None # type: str visitor_attributes = ('output', 'fragment') def __init__(self, builder: "TexinfoBuilder") -> None: super().__init__() self.builder = builder def translate(self) -> None: visitor = self.builder.create_translator(self.document, self.builder) self.visitor = cast(TexinfoTranslator, visitor) self.document.walkabout(visitor) self.visitor.finish() for attr in self.visitor_attributes: setattr(self, attr, getattr(self.visitor, attr)) class TexinfoTranslator(SphinxTranslator): builder = None # type: TexinfoBuilder ignore_missing_images = False default_elements = { 'author': '', 'body': '', 'copying': '', 'date': '', 'direntry': '', 'exampleindent': 4, 'filename': '', 'paragraphindent': 0, 'preamble': '', 'project': '', 'release': '', 'title': '', } def __init__(self, document: nodes.document, builder: "TexinfoBuilder") -> None: super().__init__(document, builder) self.init_settings() self.written_ids = set() # type: Set[str] # node names and anchors in output # node names and anchors that should be in output self.referenced_ids = set() # type: Set[str] self.indices = [] # type: List[Tuple[str, str]] # (node name, content) self.short_ids = {} # type: Dict[str, str] # anchors --> short ids self.node_names = {} # type: Dict[str, str] # node name --> node's name to display self.node_menus = {} # type: Dict[str, List[str]] # node name --> node's menu entries self.rellinks = {} # type: Dict[str, List[str]] # node name --> (next, previous, up) self.collect_indices() self.collect_node_names() self.collect_node_menus() self.collect_rellinks() self.body = [] # type: List[str] self.context = [] # type: List[str] self.descs = [] # type: List[addnodes.desc] self.previous_section = None # type: nodes.section self.section_level = 0 self.seen_title = False self.next_section_ids = set() # type: Set[str] self.escape_newlines = 0 self.escape_hyphens = 0 self.curfilestack = [] # type: List[str] self.footnotestack = [] # type: List[Dict[str, List[Union[collected_footnote, bool]]]] # NOQA self.in_footnote = 0 self.handled_abbrs = set() # type: Set[str] self.colwidths = None # type: List[int] def finish(self) -> None: if self.previous_section is None: self.add_menu('Top') for index in self.indices: name, content = index pointers = tuple([name] + self.rellinks[name]) self.body.append('\n@node %s,%s,%s,%s\n' % pointers) self.body.append('@unnumbered %s\n\n%s\n' % (name, content)) while self.referenced_ids: # handle xrefs with missing anchors r = self.referenced_ids.pop() if r not in self.written_ids: self.body.append('@anchor{%s}@w{%s}\n' % (r, ' ' * 30)) self.ensure_eol() self.fragment = ''.join(self.body) self.elements['body'] = self.fragment self.output = TEMPLATE % self.elements # -- Helper routines def init_settings(self) -> None: elements = self.elements = self.default_elements.copy() elements.update({ # if empty, the title is set to the first section title 'title': self.settings.title, 'author': self.settings.author, # if empty, use basename of input file 'filename': self.settings.texinfo_filename, 'release': self.escape(self.builder.config.release), 'project': self.escape(self.builder.config.project), 'copyright': self.escape(self.builder.config.copyright), 'date': self.escape(self.builder.config.today or format_date(self.builder.config.today_fmt or _('%b %d, %Y'), language=self.builder.config.language)) }) # title title = self.settings.title # type: str if not title: title_node = self.document.next_node(nodes.title) title = title_node.astext() if title_node else '' elements['title'] = self.escape_id(title) or '' # filename if not elements['filename']: elements['filename'] = self.document.get('source') or 'untitled' if elements['filename'][-4:] in ('.txt', '.rst'): # type: ignore elements['filename'] = elements['filename'][:-4] # type: ignore elements['filename'] += '.info' # type: ignore # direntry if self.settings.texinfo_dir_entry: entry = self.format_menu_entry( self.escape_menu(self.settings.texinfo_dir_entry), '(%s)' % elements['filename'], self.escape_arg(self.settings.texinfo_dir_description)) elements['direntry'] = ('@dircategory %s\n' '@direntry\n' '%s' '@end direntry\n') % ( self.escape_id(self.settings.texinfo_dir_category), entry) elements['copying'] = COPYING % elements # allow the user to override them all elements.update(self.settings.texinfo_elements) def collect_node_names(self) -> None: """Generates a unique id for each section. Assigns the attribute ``node_name`` to each section.""" def add_node_name(name: str) -> str: node_id = self.escape_id(name) nth, suffix = 1, '' while node_id + suffix in self.written_ids or \ node_id + suffix in self.node_names: nth += 1 suffix = '<%s>' % nth node_id += suffix self.written_ids.add(node_id) self.node_names[node_id] = name return node_id # must have a "Top" node self.document['node_name'] = 'Top' add_node_name('Top') add_node_name('top') # each index is a node self.indices = [(add_node_name(name), content) for name, content in self.indices] # each section is also a node for section in self.document.traverse(nodes.section): title = cast(nodes.TextElement, section.next_node(nodes.Titular)) name = title.astext() if title else '' section['node_name'] = add_node_name(name) def collect_node_menus(self) -> None: """Collect the menu entries for each "node" section.""" node_menus = self.node_menus targets = [self.document] # type: List[Element] targets.extend(self.document.traverse(nodes.section)) for node in targets: assert 'node_name' in node and node['node_name'] entries = [s['node_name'] for s in find_subsections(node)] node_menus[node['node_name']] = entries # try to find a suitable "Top" node title = self.document.next_node(nodes.title) top = title.parent if title else self.document if not isinstance(top, (nodes.document, nodes.section)): top = self.document if top is not self.document: entries = node_menus[top['node_name']] entries += node_menus['Top'][1:] node_menus['Top'] = entries del node_menus[top['node_name']] top['node_name'] = 'Top' # handle the indices for name, content in self.indices: node_menus[name] = [] node_menus['Top'].append(name) def collect_rellinks(self) -> None: """Collect the relative links (next, previous, up) for each "node".""" rellinks = self.rellinks node_menus = self.node_menus for id, entries in node_menus.items(): rellinks[id] = ['', '', ''] # up's for id, entries in node_menus.items(): for e in entries: rellinks[e][2] = id # next's and prev's for id, entries in node_menus.items(): for i, id in enumerate(entries): # First child's prev is empty if i != 0: rellinks[id][1] = entries[i - 1] # Last child's next is empty if i != len(entries) - 1: rellinks[id][0] = entries[i + 1] # top's next is its first child try: first = node_menus['Top'][0] except IndexError: pass else: rellinks['Top'][0] = first rellinks[first][1] = 'Top' # -- Escaping # Which characters to escape depends on the context. In some cases, # namely menus and node names, it's not possible to escape certain # characters. def escape(self, s: str) -> str: """Return a string with Texinfo command characters escaped.""" s = s.replace('@', '@@') s = s.replace('{', '@{') s = s.replace('}', '@}') # prevent `` and '' quote conversion s = s.replace('``', "`@w{`}") s = s.replace("''", "'@w{'}") return s def escape_arg(self, s: str) -> str: """Return an escaped string suitable for use as an argument to a Texinfo command.""" s = self.escape(s) # commas are the argument delimiters s = s.replace(',', '@comma{}') # normalize white space s = ' '.join(s.split()).strip() return s def escape_id(self, s: str) -> str: """Return an escaped string suitable for node names and anchors.""" bad_chars = ',:()' for bc in bad_chars: s = s.replace(bc, ' ') if re.search('[^ .]', s): # remove DOTs if name contains other characters s = s.replace('.', ' ') s = ' '.join(s.split()).strip() return self.escape(s) def escape_menu(self, s: str) -> str: """Return an escaped string suitable for menu entries.""" s = self.escape_arg(s) s = s.replace(':', ';') s = ' '.join(s.split()).strip() return s def ensure_eol(self) -> None: """Ensure the last line in body is terminated by new line.""" if self.body and self.body[-1][-1:] != '\n': self.body.append('\n') def format_menu_entry(self, name: str, node_name: str, desc: str) -> str: if name == node_name: s = '* %s:: ' % (name,) else: s = '* %s: %s. ' % (name, node_name) offset = max((24, (len(name) + 4) % 78)) wdesc = '\n'.join(' ' * offset + l for l in textwrap.wrap(desc, width=78 - offset)) return s + wdesc.strip() + '\n' def add_menu_entries(self, entries: List[str], reg: Pattern = re.compile(r'\s+---?\s+') ) -> None: for entry in entries: name = self.node_names[entry] # special formatting for entries that are divided by an em-dash try: parts = reg.split(name, 1) except TypeError: # could be a gettext proxy parts = [name] if len(parts) == 2: name, desc = parts else: desc = '' name = self.escape_menu(name) desc = self.escape(desc) self.body.append(self.format_menu_entry(name, entry, desc)) def add_menu(self, node_name: str) -> None: entries = self.node_menus[node_name] if not entries: return self.body.append('\n@menu\n') self.add_menu_entries(entries) if (node_name != 'Top' or not self.node_menus[entries[0]] or self.builder.config.texinfo_no_detailmenu): self.body.append('\n@end menu\n') return def _add_detailed_menu(name: str) -> None: entries = self.node_menus[name] if not entries: return self.body.append('\n%s\n\n' % (self.escape(self.node_names[name],))) self.add_menu_entries(entries) for subentry in entries: _add_detailed_menu(subentry) self.body.append('\n@detailmenu\n' ' --- The Detailed Node Listing ---\n') for entry in entries: _add_detailed_menu(entry) self.body.append('\n@end detailmenu\n' '@end menu\n') def tex_image_length(self, width_str: str) -> str: match = re.match(r'(\d*\.?\d*)\s*(\S*)', width_str) if not match: # fallback return width_str res = width_str amount, unit = match.groups()[:2] if not unit or unit == "px": # pixels: let TeX alone return '' elif unit == "%": # a4paper: textwidth=418.25368pt res = "%d.0pt" % (float(amount) * 4.1825368) return res def collect_indices(self) -> None: def generate(content: List[Tuple[str, List[IndexEntry]]], collapsed: bool) -> str: ret = ['\n@menu\n'] for letter, entries in content: for entry in entries: if not entry[3]: continue name = self.escape_menu(entry[0]) sid = self.get_short_id('%s:%s' % (entry[2], entry[3])) desc = self.escape_arg(entry[6]) me = self.format_menu_entry(name, sid, desc) ret.append(me) ret.append('@end menu\n') return ''.join(ret) indices_config = self.builder.config.texinfo_domain_indices if indices_config: for domain in self.builder.env.domains.values(): for indexcls in domain.indices: indexname = '%s-%s' % (domain.name, indexcls.name) if isinstance(indices_config, list): if indexname not in indices_config: continue content, collapsed = indexcls(domain).generate( self.builder.docnames) if not content: continue self.indices.append((indexcls.localname, generate(content, collapsed))) # only add the main Index if it's not empty domain = cast(IndexDomain, self.builder.env.get_domain('index')) for docname in self.builder.docnames: if domain.entries[docname]: self.indices.append((_('Index'), '\n@printindex ge\n')) break # this is copied from the latex writer # TODO: move this to sphinx.util def collect_footnotes(self, node: Element) -> Dict[str, List[Union[collected_footnote, bool]]]: # NOQA def footnotes_under(n: Element) -> Iterator[nodes.footnote]: if isinstance(n, nodes.footnote): yield n else: for c in n.children: if isinstance(c, addnodes.start_of_file): continue elif isinstance(c, nodes.Element): yield from footnotes_under(c) fnotes = {} # type: Dict[str, List[Union[collected_footnote, bool]]] for fn in footnotes_under(node): label = cast(nodes.label, fn[0]) num = label.astext().strip() fnotes[num] = [collected_footnote('', *fn.children), False] return fnotes # -- xref handling def get_short_id(self, id: str) -> str: """Return a shorter 'id' associated with ``id``.""" # Shorter ids improve paragraph filling in places # that the id is hidden by Emacs. try: sid = self.short_ids[id] except KeyError: sid = hex(len(self.short_ids))[2:] self.short_ids[id] = sid return sid def add_anchor(self, id: str, node: Node) -> None: if id.startswith('index-'): return id = self.curfilestack[-1] + ':' + id eid = self.escape_id(id) sid = self.get_short_id(id) for id in (eid, sid): if id not in self.written_ids: self.body.append('@anchor{%s}' % id) self.written_ids.add(id) def add_xref(self, id: str, name: str, node: Node) -> None: name = self.escape_menu(name) sid = self.get_short_id(id) self.body.append('@ref{%s,,%s}' % (sid, name)) self.referenced_ids.add(sid) self.referenced_ids.add(self.escape_id(id)) # -- Visiting def visit_document(self, node: Element) -> None: self.footnotestack.append(self.collect_footnotes(node)) self.curfilestack.append(node.get('docname', '')) if 'docname' in node: self.add_anchor(':doc', node) def depart_document(self, node: Element) -> None: self.footnotestack.pop() self.curfilestack.pop() def visit_Text(self, node: Text) -> None: s = self.escape(node.astext()) if self.escape_newlines: s = s.replace('\n', ' ') if self.escape_hyphens: # prevent "--" and "---" conversion s = s.replace('-', '@w{-}') self.body.append(s) def depart_Text(self, node: Text) -> None: pass def visit_section(self, node: Element) -> None: self.next_section_ids.update(node.get('ids', [])) if not self.seen_title: return if self.previous_section: self.add_menu(self.previous_section['node_name']) else: self.add_menu('Top') node_name = node['node_name'] pointers = tuple([node_name] + self.rellinks[node_name]) self.body.append('\n@node %s,%s,%s,%s\n' % pointers) for id in sorted(self.next_section_ids): self.add_anchor(id, node) self.next_section_ids.clear() self.previous_section = cast(nodes.section, node) self.section_level += 1 def depart_section(self, node: Element) -> None: self.section_level -= 1 headings = ( '@unnumbered', '@chapter', '@section', '@subsection', '@subsubsection', ) rubrics = ( '@heading', '@subheading', '@subsubheading', ) def visit_title(self, node: Element) -> None: if not self.seen_title: self.seen_title = True raise nodes.SkipNode parent = node.parent if isinstance(parent, nodes.table): return if isinstance(parent, (nodes.Admonition, nodes.sidebar, nodes.topic)): raise nodes.SkipNode elif not isinstance(parent, nodes.section): logger.warning(__('encountered title node not in section, topic, table, ' 'admonition or sidebar'), location=node) self.visit_rubric(node) else: try: heading = self.headings[self.section_level] except IndexError: heading = self.headings[-1] self.body.append('\n%s ' % heading) def depart_title(self, node: Element) -> None: self.body.append('\n\n') def visit_rubric(self, node: Element) -> None: if len(node) == 1 and node.astext() in ('Footnotes', _('Footnotes')): raise nodes.SkipNode try: rubric = self.rubrics[self.section_level] except IndexError: rubric = self.rubrics[-1] self.body.append('\n%s ' % rubric) self.escape_newlines += 1 def depart_rubric(self, node: Element) -> None: self.escape_newlines -= 1 self.body.append('\n\n') def visit_subtitle(self, node: Element) -> None: self.body.append('\n\n@noindent\n') def depart_subtitle(self, node: Element) -> None: self.body.append('\n\n') # -- References def visit_target(self, node: Element) -> None: # postpone the labels until after the sectioning command parindex = node.parent.index(node) try: try: next = node.parent[parindex + 1] except IndexError: # last node in parent, look at next after parent # (for section of equal level) next = node.parent.parent[node.parent.parent.index(node.parent)] if isinstance(next, nodes.section): if node.get('refid'): self.next_section_ids.add(node['refid']) self.next_section_ids.update(node['ids']) return except (IndexError, AttributeError): pass if 'refuri' in node: return if node.get('refid'): self.add_anchor(node['refid'], node) for id in node['ids']: self.add_anchor(id, node) def depart_target(self, node: Element) -> None: pass def visit_reference(self, node: Element) -> None: # an xref's target is displayed in Info so we ignore a few # cases for the sake of appearance if isinstance(node.parent, (nodes.title, addnodes.desc_type)): return if isinstance(node[0], nodes.image): return name = node.get('name', node.astext()).strip() uri = node.get('refuri', '') if not uri and node.get('refid'): uri = '%' + self.curfilestack[-1] + '#' + node['refid'] if not uri: return if uri.startswith('mailto:'): uri = self.escape_arg(uri[7:]) name = self.escape_arg(name) if not name or name == uri: self.body.append('@email{%s}' % uri) else: self.body.append('@email{%s,%s}' % (uri, name)) elif uri.startswith('#'): # references to labels in the same document id = self.curfilestack[-1] + ':' + uri[1:] self.add_xref(id, name, node) elif uri.startswith('%'): # references to documents or labels inside documents hashindex = uri.find('#') if hashindex == -1: # reference to the document id = uri[1:] + '::doc' else: # reference to a label id = uri[1:].replace('#', ':') self.add_xref(id, name, node) elif uri.startswith('info:'): # references to an external Info file uri = uri[5:].replace('_', ' ') uri = self.escape_arg(uri) id = 'Top' if '#' in uri: uri, id = uri.split('#', 1) id = self.escape_id(id) name = self.escape_menu(name) if name == id: self.body.append('@ref{%s,,,%s}' % (id, uri)) else: self.body.append('@ref{%s,,%s,%s}' % (id, name, uri)) else: uri = self.escape_arg(uri) name = self.escape_arg(name) show_urls = self.builder.config.texinfo_show_urls if self.in_footnote: show_urls = 'inline' if not name or uri == name: self.body.append('@indicateurl{%s}' % uri) elif show_urls == 'inline': self.body.append('@uref{%s,%s}' % (uri, name)) elif show_urls == 'no': self.body.append('@uref{%s,,%s}' % (uri, name)) else: self.body.append('%s@footnote{%s}' % (name, uri)) raise nodes.SkipNode def depart_reference(self, node: Element) -> None: pass def visit_number_reference(self, node: Element) -> None: text = nodes.Text(node.get('title', '#')) self.visit_Text(text) raise nodes.SkipNode def visit_title_reference(self, node: Element) -> None: text = node.astext() self.body.append('@cite{%s}' % self.escape_arg(text)) raise nodes.SkipNode # -- Blocks def visit_paragraph(self, node: Element) -> None: self.body.append('\n') def depart_paragraph(self, node: Element) -> None: self.body.append('\n') def visit_block_quote(self, node: Element) -> None: self.body.append('\n@quotation\n') def depart_block_quote(self, node: Element) -> None: self.ensure_eol() self.body.append('@end quotation\n') def visit_literal_block(self, node: Element) -> None: self.body.append('\n@example\n') def depart_literal_block(self, node: Element) -> None: self.ensure_eol() self.body.append('@end example\n') visit_doctest_block = visit_literal_block depart_doctest_block = depart_literal_block def visit_line_block(self, node: Element) -> None: if not isinstance(node.parent, nodes.line_block): self.body.append('\n\n') self.body.append('@display\n') def depart_line_block(self, node: Element) -> None: self.body.append('@end display\n') if not isinstance(node.parent, nodes.line_block): self.body.append('\n\n') def visit_line(self, node: Element) -> None: self.escape_newlines += 1 def depart_line(self, node: Element) -> None: self.body.append('@w{ }\n') self.escape_newlines -= 1 # -- Inline def visit_strong(self, node: Element) -> None: self.body.append('@strong{') def depart_strong(self, node: Element) -> None: self.body.append('}') def visit_emphasis(self, node: Element) -> None: self.body.append('@emph{') def depart_emphasis(self, node: Element) -> None: self.body.append('}') def visit_literal(self, node: Element) -> None: self.body.append('@code{') def depart_literal(self, node: Element) -> None: self.body.append('}') def visit_superscript(self, node: Element) -> None: self.body.append('@w{^') def depart_superscript(self, node: Element) -> None: self.body.append('}') def visit_subscript(self, node: Element) -> None: self.body.append('@w{[') def depart_subscript(self, node: Element) -> None: self.body.append(']}') # -- Footnotes def visit_footnote(self, node: Element) -> None: raise nodes.SkipNode def visit_collected_footnote(self, node: Element) -> None: self.in_footnote += 1 self.body.append('@footnote{') def depart_collected_footnote(self, node: Element) -> None: self.body.append('}') self.in_footnote -= 1 def visit_footnote_reference(self, node: Element) -> None: num = node.astext().strip() try: footnode, used = self.footnotestack[-1][num] except (KeyError, IndexError) as exc: raise nodes.SkipNode from exc # footnotes are repeated for each reference footnode.walkabout(self) # type: ignore raise nodes.SkipChildren def visit_citation(self, node: Element) -> None: self.body.append('\n') for id in node.get('ids'): self.add_anchor(id, node) self.escape_newlines += 1 def depart_citation(self, node: Element) -> None: self.escape_newlines -= 1 def visit_citation_reference(self, node: Element) -> None: self.body.append('@w{[') def depart_citation_reference(self, node: Element) -> None: self.body.append(']}') # -- Lists def visit_bullet_list(self, node: Element) -> None: bullet = node.get('bullet', '*') self.body.append('\n\n@itemize %s\n' % bullet) def depart_bullet_list(self, node: Element) -> None: self.ensure_eol() self.body.append('@end itemize\n') def visit_enumerated_list(self, node: Element) -> None: # doesn't support Roman numerals enum = node.get('enumtype', 'arabic') starters = {'arabic': '', 'loweralpha': 'a', 'upperalpha': 'A'} start = node.get('start', starters.get(enum, '')) self.body.append('\n\n@enumerate %s\n' % start) def depart_enumerated_list(self, node: Element) -> None: self.ensure_eol() self.body.append('@end enumerate\n') def visit_list_item(self, node: Element) -> None: self.body.append('\n@item ') def depart_list_item(self, node: Element) -> None: pass # -- Option List def visit_option_list(self, node: Element) -> None: self.body.append('\n\n@table @option\n') def depart_option_list(self, node: Element) -> None: self.ensure_eol() self.body.append('@end table\n') def visit_option_list_item(self, node: Element) -> None: pass def depart_option_list_item(self, node: Element) -> None: pass def visit_option_group(self, node: Element) -> None: self.at_item_x = '@item' def depart_option_group(self, node: Element) -> None: pass def visit_option(self, node: Element) -> None: self.escape_hyphens += 1 self.body.append('\n%s ' % self.at_item_x) self.at_item_x = '@itemx' def depart_option(self, node: Element) -> None: self.escape_hyphens -= 1 def visit_option_string(self, node: Element) -> None: pass def depart_option_string(self, node: Element) -> None: pass def visit_option_argument(self, node: Element) -> None: self.body.append(node.get('delimiter', ' ')) def depart_option_argument(self, node: Element) -> None: pass def visit_description(self, node: Element) -> None: self.body.append('\n') def depart_description(self, node: Element) -> None: pass # -- Definitions def visit_definition_list(self, node: Element) -> None: self.body.append('\n\n@table @asis\n') def depart_definition_list(self, node: Element) -> None: self.ensure_eol() self.body.append('@end table\n') def visit_definition_list_item(self, node: Element) -> None: self.at_item_x = '@item' def depart_definition_list_item(self, node: Element) -> None: pass def visit_term(self, node: Element) -> None: for id in node.get('ids'): self.add_anchor(id, node) # anchors and indexes need to go in front for n in node[::]: if isinstance(n, (addnodes.index, nodes.target)): n.walkabout(self) node.remove(n) self.body.append('\n%s ' % self.at_item_x) self.at_item_x = '@itemx' def depart_term(self, node: Element) -> None: pass def visit_classifier(self, node: Element) -> None: self.body.append(' : ') def depart_classifier(self, node: Element) -> None: pass def visit_definition(self, node: Element) -> None: self.body.append('\n') def depart_definition(self, node: Element) -> None: pass # -- Tables def visit_table(self, node: Element) -> None: self.entry_sep = '@item' def depart_table(self, node: Element) -> None: self.body.append('\n@end multitable\n\n') def visit_tabular_col_spec(self, node: Element) -> None: pass def depart_tabular_col_spec(self, node: Element) -> None: pass def visit_colspec(self, node: Element) -> None: self.colwidths.append(node['colwidth']) if len(self.colwidths) != self.n_cols: return self.body.append('\n\n@multitable ') for i, n in enumerate(self.colwidths): self.body.append('{%s} ' % ('x' * (n + 2))) def depart_colspec(self, node: Element) -> None: pass def visit_tgroup(self, node: Element) -> None: self.colwidths = [] self.n_cols = node['cols'] def depart_tgroup(self, node: Element) -> None: pass def visit_thead(self, node: Element) -> None: self.entry_sep = '@headitem' def depart_thead(self, node: Element) -> None: pass def visit_tbody(self, node: Element) -> None: pass def depart_tbody(self, node: Element) -> None: pass def visit_row(self, node: Element) -> None: pass def depart_row(self, node: Element) -> None: self.entry_sep = '@item' def visit_entry(self, node: Element) -> None: self.body.append('\n%s\n' % self.entry_sep) self.entry_sep = '@tab' def depart_entry(self, node: Element) -> None: for i in range(node.get('morecols', 0)): self.body.append('\n@tab\n') # -- Field Lists def visit_field_list(self, node: Element) -> None: pass def depart_field_list(self, node: Element) -> None: pass def visit_field(self, node: Element) -> None: self.body.append('\n') def depart_field(self, node: Element) -> None: self.body.append('\n') def visit_field_name(self, node: Element) -> None: self.ensure_eol() self.body.append('@*') def depart_field_name(self, node: Element) -> None: self.body.append(': ') def visit_field_body(self, node: Element) -> None: pass def depart_field_body(self, node: Element) -> None: pass # -- Admonitions def visit_admonition(self, node: Element, name: str = '') -> None: if not name: title = cast(nodes.title, node[0]) name = self.escape(title.astext()) self.body.append('\n@cartouche\n@quotation %s ' % name) def _visit_named_admonition(self, node: Element) -> None: label = admonitionlabels[node.tagname] self.body.append('\n@cartouche\n@quotation %s ' % label) def depart_admonition(self, node: Element) -> None: self.ensure_eol() self.body.append('@end quotation\n' '@end cartouche\n') visit_attention = _visit_named_admonition depart_attention = depart_admonition visit_caution = _visit_named_admonition depart_caution = depart_admonition visit_danger = _visit_named_admonition depart_danger = depart_admonition visit_error = _visit_named_admonition depart_error = depart_admonition visit_hint = _visit_named_admonition depart_hint = depart_admonition visit_important = _visit_named_admonition depart_important = depart_admonition visit_note = _visit_named_admonition depart_note = depart_admonition visit_tip = _visit_named_admonition depart_tip = depart_admonition visit_warning = _visit_named_admonition depart_warning = depart_admonition # -- Misc def visit_docinfo(self, node: Element) -> None: raise nodes.SkipNode def visit_generated(self, node: Element) -> None: raise nodes.SkipNode def visit_header(self, node: Element) -> None: raise nodes.SkipNode def visit_footer(self, node: Element) -> None: raise nodes.SkipNode def visit_container(self, node: Element) -> None: if node.get('literal_block'): self.body.append('\n\n@float LiteralBlock\n') def depart_container(self, node: Element) -> None: if node.get('literal_block'): self.body.append('\n@end float\n\n') def visit_decoration(self, node: Element) -> None: pass def depart_decoration(self, node: Element) -> None: pass def visit_topic(self, node: Element) -> None: # ignore TOC's since we have to have a "menu" anyway if 'contents' in node.get('classes', []): raise nodes.SkipNode title = cast(nodes.title, node[0]) self.visit_rubric(title) self.body.append('%s\n' % self.escape(title.astext())) self.depart_rubric(title) def depart_topic(self, node: Element) -> None: pass def visit_transition(self, node: Element) -> None: self.body.append('\n\n%s\n\n' % ('_' * 66)) def depart_transition(self, node: Element) -> None: pass def visit_attribution(self, node: Element) -> None: self.body.append('\n\n@center --- ') def depart_attribution(self, node: Element) -> None: self.body.append('\n\n') def visit_raw(self, node: Element) -> None: format = node.get('format', '').split() if 'texinfo' in format or 'texi' in format: self.body.append(node.astext()) raise nodes.SkipNode def visit_figure(self, node: Element) -> None: self.body.append('\n\n@float Figure\n') def depart_figure(self, node: Element) -> None: self.body.append('\n@end float\n\n') def visit_caption(self, node: Element) -> None: if (isinstance(node.parent, nodes.figure) or (isinstance(node.parent, nodes.container) and node.parent.get('literal_block'))): self.body.append('\n@caption{') else: logger.warning(__('caption not inside a figure.'), location=node) def depart_caption(self, node: Element) -> None: if (isinstance(node.parent, nodes.figure) or (isinstance(node.parent, nodes.container) and node.parent.get('literal_block'))): self.body.append('}\n') def visit_image(self, node: Element) -> None: if node['uri'] in self.builder.images: uri = self.builder.images[node['uri']] else: # missing image! if self.ignore_missing_images: return uri = node['uri'] if uri.find('://') != -1: # ignore remote images return name, ext = path.splitext(uri) attrs = node.attributes # width and height ignored in non-tex output width = self.tex_image_length(attrs.get('width', '')) height = self.tex_image_length(attrs.get('height', '')) alt = self.escape_arg(attrs.get('alt', '')) filename = "%s-figures/%s" % (self.elements['filename'][:-5], name) # type: ignore self.body.append('\n@image{%s,%s,%s,%s,%s}\n' % (filename, width, height, alt, ext[1:])) def depart_image(self, node: Element) -> None: pass def visit_compound(self, node: Element) -> None: pass def depart_compound(self, node: Element) -> None: pass def visit_sidebar(self, node: Element) -> None: self.visit_topic(node) def depart_sidebar(self, node: Element) -> None: self.depart_topic(node) def visit_label(self, node: Element) -> None: self.body.append('@w{(') def depart_label(self, node: Element) -> None: self.body.append(')} ') def visit_legend(self, node: Element) -> None: pass def depart_legend(self, node: Element) -> None: pass def visit_substitution_reference(self, node: Element) -> None: pass def depart_substitution_reference(self, node: Element) -> None: pass def visit_substitution_definition(self, node: Element) -> None: raise nodes.SkipNode def visit_system_message(self, node: Element) -> None: self.body.append('\n@verbatim\n' '\n' '@end verbatim\n' % node.astext()) raise nodes.SkipNode def visit_comment(self, node: Element) -> None: self.body.append('\n') for line in node.astext().splitlines(): self.body.append('@c %s\n' % line) raise nodes.SkipNode def visit_problematic(self, node: Element) -> None: self.body.append('>>') def depart_problematic(self, node: Element) -> None: self.body.append('<<') def unimplemented_visit(self, node: Element) -> None: logger.warning(__("unimplemented node type: %r"), node, location=node) def unknown_visit(self, node: Node) -> None: logger.warning(__("unknown node type: %r"), node, location=node) def unknown_departure(self, node: Node) -> None: pass # -- Sphinx specific def visit_productionlist(self, node: Element) -> None: self.visit_literal_block(None) names = [] productionlist = cast(Iterable[addnodes.production], node) for production in productionlist: names.append(production['tokenname']) maxlen = max(len(name) for name in names) for production in productionlist: if production['tokenname']: for id in production.get('ids'): self.add_anchor(id, production) s = production['tokenname'].ljust(maxlen) + ' ::=' else: s = '%s ' % (' ' * maxlen) self.body.append(self.escape(s)) self.body.append(self.escape(production.astext() + '\n')) self.depart_literal_block(None) raise nodes.SkipNode def visit_production(self, node: Element) -> None: pass def depart_production(self, node: Element) -> None: pass def visit_literal_emphasis(self, node: Element) -> None: self.body.append('@code{') def depart_literal_emphasis(self, node: Element) -> None: self.body.append('}') def visit_literal_strong(self, node: Element) -> None: self.body.append('@code{') def depart_literal_strong(self, node: Element) -> None: self.body.append('}') def visit_index(self, node: Element) -> None: # terminate the line but don't prevent paragraph breaks if isinstance(node.parent, nodes.paragraph): self.ensure_eol() else: self.body.append('\n') for entry in node['entries']: typ, text, tid, text2, key_ = entry text = self.escape_menu(text) self.body.append('@geindex %s\n' % text) def visit_versionmodified(self, node: Element) -> None: self.body.append('\n') def depart_versionmodified(self, node: Element) -> None: self.body.append('\n') def visit_start_of_file(self, node: Element) -> None: # add a document target self.next_section_ids.add(':doc') self.curfilestack.append(node['docname']) self.footnotestack.append(self.collect_footnotes(node)) def depart_start_of_file(self, node: Element) -> None: self.curfilestack.pop() self.footnotestack.pop() def visit_centered(self, node: Element) -> None: txt = self.escape_arg(node.astext()) self.body.append('\n\n@center %s\n\n' % txt) raise nodes.SkipNode def visit_seealso(self, node: Element) -> None: self.body.append('\n\n@subsubheading %s\n\n' % admonitionlabels['seealso']) def depart_seealso(self, node: Element) -> None: self.body.append('\n') def visit_meta(self, node: Element) -> None: raise nodes.SkipNode def visit_glossary(self, node: Element) -> None: pass def depart_glossary(self, node: Element) -> None: pass 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.body.append('\n\n') self.body.append(', '.join(n.astext() for n in list_items) + '.') self.body.append('\n\n') raise nodes.SkipNode # -- Desc def visit_desc(self, node: addnodes.desc) -> None: self.descs.append(node) self.at_deffnx = '@deffn' def depart_desc(self, node: addnodes.desc) -> None: self.descs.pop() self.ensure_eol() self.body.append('@end deffn\n') def visit_desc_signature(self, node: Element) -> None: self.escape_hyphens += 1 objtype = node.parent['objtype'] if objtype != 'describe': for id in node.get('ids'): self.add_anchor(id, node) # use the full name of the objtype for the category try: domain = self.builder.env.get_domain(node.parent['domain']) primary = self.builder.config.primary_domain name = domain.get_type_name(domain.object_types[objtype], primary == domain.name) except (KeyError, ExtensionError): name = objtype # by convention, the deffn category should be capitalized like a title category = self.escape_arg(smart_capwords(name)) self.body.append('\n%s {%s} ' % (self.at_deffnx, category)) self.at_deffnx = '@deffnx' self.desc_type_name = name def depart_desc_signature(self, node: Element) -> None: self.body.append("\n") self.escape_hyphens -= 1 self.desc_type_name = None def visit_desc_signature_line(self, node: Element) -> None: pass def depart_desc_signature_line(self, node: Element) -> None: pass def visit_desc_name(self, node: Element) -> None: pass def depart_desc_name(self, node: Element) -> None: pass def visit_desc_addname(self, node: Element) -> None: pass def depart_desc_addname(self, node: Element) -> None: pass def visit_desc_type(self, node: Element) -> None: pass def depart_desc_type(self, node: Element) -> None: pass def visit_desc_returns(self, node: Element) -> None: self.body.append(' -> ') def depart_desc_returns(self, node: Element) -> None: pass def visit_desc_parameterlist(self, node: Element) -> None: self.body.append(' (') self.first_param = 1 def depart_desc_parameterlist(self, node: Element) -> None: self.body.append(')') def visit_desc_parameter(self, node: Element) -> None: if not self.first_param: self.body.append(', ') else: self.first_param = 0 text = self.escape(node.astext()) # replace no-break spaces with normal ones text = text.replace(' ', '@w{ }') self.body.append(text) raise nodes.SkipNode def visit_desc_optional(self, node: Element) -> None: self.body.append('[') def depart_desc_optional(self, node: Element) -> None: self.body.append(']') def visit_desc_annotation(self, node: Element) -> None: # Try to avoid duplicating info already displayed by the deffn category. # e.g. # @deffn {Class} Foo # -- instead of -- # @deffn {Class} class Foo txt = node.astext().strip() if ((self.descs and txt == self.descs[-1]['objtype']) or (self.desc_type_name and txt in self.desc_type_name.split())): raise nodes.SkipNode def depart_desc_annotation(self, node: Element) -> None: pass def visit_desc_content(self, node: Element) -> None: pass def depart_desc_content(self, node: Element) -> None: pass def visit_inline(self, node: Element) -> None: pass def depart_inline(self, node: Element) -> None: pass def visit_abbreviation(self, node: Element) -> None: abbr = node.astext() self.body.append('@abbr{') if node.hasattr('explanation') and abbr not in self.handled_abbrs: self.context.append(',%s}' % self.escape_arg(node['explanation'])) self.handled_abbrs.add(abbr) else: self.context.append('}') def depart_abbreviation(self, node: Element) -> None: self.body.append(self.context.pop()) def visit_manpage(self, node: Element) -> None: return self.visit_literal_emphasis(node) def depart_manpage(self, node: Element) -> None: return self.depart_literal_emphasis(node) def visit_download_reference(self, node: Element) -> None: pass def depart_download_reference(self, node: Element) -> None: pass def visit_hlist(self, node: Element) -> None: self.visit_bullet_list(node) def depart_hlist(self, node: Element) -> None: self.depart_bullet_list(node) def visit_hlistcol(self, node: Element) -> None: pass def depart_hlistcol(self, node: Element) -> None: pass def visit_pending_xref(self, node: Element) -> None: pass def depart_pending_xref(self, node: Element) -> None: pass def visit_math(self, node: Element) -> None: self.body.append('@math{' + self.escape_arg(node.astext()) + '}') raise nodes.SkipNode def visit_math_block(self, node: Element) -> None: if node.get('label'): self.add_anchor(node['label'], node) self.body.append('\n\n@example\n%s\n@end example\n\n' % self.escape_arg(node.astext())) raise nodes.SkipNode @property def desc(self) -> Optional[addnodes.desc]: warnings.warn('TexinfoWriter.desc is deprecated.', RemovedInSphinx50Warning) if len(self.descs): return self.descs[-1] else: return None