mirror of
https://github.com/YosysHQ/yosys
synced 2025-07-26 22:17:55 +00:00
37782cb92b
Keep techlibs folder hierarchy. techlibs/* and passes/* groups are now nested under index_techlibs and index_passes respectively, with most (all?) of the passes/* pages getting proper headings, as well as backends/frontends/kernel. `index_passes_techmap` also references `index_techlibs`. Split command reference toc in twain, one with maxdepth=2 and one with maxdepth=3, since passes and techlibs now have an extra level of nesting. Move the `cmd_ref` link to the command reference, instead of top of the page. Remove `index_internal` and `index_other` from the toc, and mark the pages as orphan. Internal commands get a note callout after the command reference toc (although this doesn't work for the pdf build), while other commands are linked in the warning for missing `source_location` (since that *should* be the only time when there are any commands in the "unknown" group). Update autodoc extension versions, and mark the directives extension as not `parallel_read_safe` (it might be, but I'm not sure about how the xref lookups work if it is parallel so better to be safe).
741 lines
26 KiB
Python
741 lines
26 KiB
Python
# based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
from typing import cast
|
|
import warnings
|
|
|
|
from docutils import nodes
|
|
from docutils.nodes import Node, Element, Text
|
|
from docutils.parsers.rst import directives
|
|
from docutils.parsers.rst.states import Inliner
|
|
from sphinx.application import Sphinx
|
|
from sphinx.domains import Domain, Index
|
|
from sphinx.domains.std import StandardDomain
|
|
from sphinx.environment import BuildEnvironment
|
|
from sphinx.roles import XRefRole
|
|
from sphinx.directives import ObjectDescription
|
|
from sphinx.directives.code import container_wrapper
|
|
from sphinx.util.nodes import make_refnode
|
|
from sphinx.util.docfields import Field, GroupedField
|
|
from sphinx import addnodes
|
|
|
|
class TocNode(ObjectDescription):
|
|
def add_target_and_index(
|
|
self,
|
|
name: str,
|
|
sig: str,
|
|
signode: addnodes.desc_signature
|
|
) -> None:
|
|
idx = ".".join(name.split("::"))
|
|
signode['ids'].append(idx)
|
|
|
|
def _object_hierarchy_parts(self, sig_node: addnodes.desc_signature) -> tuple[str, ...]:
|
|
if 'tocname' not in sig_node:
|
|
return ()
|
|
|
|
modname = sig_node.get('module')
|
|
fullname = sig_node['fullname']
|
|
|
|
if modname:
|
|
return (modname, *fullname.split('::'))
|
|
else:
|
|
return tuple(fullname.split('::'))
|
|
|
|
def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str:
|
|
if not sig_node.get('_toc_parts'):
|
|
return ''
|
|
|
|
config = self.env.app.config
|
|
objtype = sig_node.parent.get('objtype')
|
|
*parents, name = sig_node['_toc_parts']
|
|
if config.toc_object_entries_show_parents == 'domain':
|
|
return sig_node.get('tocname', name)
|
|
if config.toc_object_entries_show_parents == 'hide':
|
|
return name
|
|
if config.toc_object_entries_show_parents == 'all':
|
|
return '.'.join(parents + [name])
|
|
return ''
|
|
|
|
class CommandNode(TocNode):
|
|
"""A custom node that describes a command."""
|
|
|
|
name = 'cmd'
|
|
required_arguments = 1
|
|
|
|
option_spec = TocNode.option_spec.copy()
|
|
option_spec.update({
|
|
'title': directives.unchanged,
|
|
'tags': directives.unchanged
|
|
})
|
|
|
|
doc_field_types = [
|
|
GroupedField('opts', label='Options', names=('option', 'options', 'opt', 'opts')),
|
|
]
|
|
|
|
def handle_signature(self, sig, signode: addnodes.desc_signature):
|
|
signode['fullname'] = sig
|
|
signode += addnodes.desc_addname(text="yosys> help ")
|
|
signode += addnodes.desc_name(text=sig)
|
|
return signode['fullname']
|
|
|
|
def add_target_and_index(self, name_cls, sig, signode):
|
|
idx = type(self).name + '-' + sig
|
|
signode['ids'].append(idx)
|
|
if 'noindex' not in self.options:
|
|
name = "{}.{}.{}".format(self.name, type(self).__name__, sig)
|
|
tagmap = self.env.domaindata[type(self).name]['obj2tag']
|
|
tagmap[name] = list(self.options.get('tags', '').split(' '))
|
|
title = self.options.get('title', sig)
|
|
titlemap = self.env.domaindata[type(self).name]['obj2title']
|
|
titlemap[name] = title
|
|
objs = self.env.domaindata[type(self).name]['objects']
|
|
# (name, sig, typ, docname, anchor, prio)
|
|
objs.append((name,
|
|
sig,
|
|
type(self).name,
|
|
self.env.docname,
|
|
idx,
|
|
0))
|
|
|
|
class CommandUsageNode(TocNode):
|
|
"""A custom node that describes command usages"""
|
|
|
|
name = 'cmdusage'
|
|
|
|
option_spec = TocNode.option_spec
|
|
option_spec.update({
|
|
'usage': directives.unchanged,
|
|
})
|
|
|
|
doc_field_types = [
|
|
GroupedField('opts', label='Options', names=('option', 'options', 'opt', 'opts')),
|
|
]
|
|
|
|
def handle_signature(self, sig: str, signode: addnodes.desc_signature):
|
|
parts = sig.split('::')
|
|
if len(parts) > 2: parts.pop(0)
|
|
use = parts[-1]
|
|
signode['fullname'] = '::'.join(parts)
|
|
usage = self.options.get('usage', use)
|
|
if usage:
|
|
signode['tocname'] = usage
|
|
signode += addnodes.desc_name(text=usage)
|
|
return signode['fullname']
|
|
|
|
def add_target_and_index(
|
|
self,
|
|
name: str,
|
|
sig: str,
|
|
signode: addnodes.desc_signature
|
|
) -> None:
|
|
idx = ".".join(name.split("::"))
|
|
signode['ids'].append(idx)
|
|
if 'noindex' not in self.options:
|
|
tocname: str = signode.get('tocname', name)
|
|
objs = self.env.domaindata[self.domain]['objects']
|
|
# (name, sig, typ, docname, anchor, prio)
|
|
objs.append((name,
|
|
tocname,
|
|
type(self).name,
|
|
self.env.docname,
|
|
idx,
|
|
1))
|
|
|
|
class CommandOptionGroupNode(CommandUsageNode):
|
|
"""A custom node that describes a group of related options"""
|
|
|
|
name = 'cmdoptiongroup'
|
|
|
|
option_spec = CommandUsageNode.option_spec
|
|
|
|
doc_field_types = [
|
|
Field('opt', ('option',), label='', rolename='option')
|
|
]
|
|
|
|
def transform_content(self, contentnode: addnodes.desc_content) -> None:
|
|
"""hack `:option -thing: desc` into a proper option list"""
|
|
newchildren = []
|
|
for node in contentnode:
|
|
newnode = node
|
|
if isinstance(node, nodes.field_list):
|
|
newnode = nodes.option_list()
|
|
for field in node:
|
|
is_option = False
|
|
option_list_item = nodes.option_list_item()
|
|
for child in field:
|
|
if isinstance(child, nodes.field_name):
|
|
option_group = nodes.option_group()
|
|
option_list_item += option_group
|
|
option = nodes.option()
|
|
option_group += option
|
|
name, text = child.rawsource.split(' ', 1)
|
|
is_option = name == 'option'
|
|
option += nodes.option_string(text=text)
|
|
if not is_option: warnings.warn(f'unexpected option \'{name}\' in {field.source}')
|
|
elif isinstance(child, nodes.field_body):
|
|
description = nodes.description()
|
|
description += child.children
|
|
option_list_item += description
|
|
if is_option:
|
|
newnode += option_list_item
|
|
newchildren.append(newnode)
|
|
contentnode.children = newchildren
|
|
|
|
class PropNode(TocNode):
|
|
name = 'prop'
|
|
fieldname = 'props'
|
|
|
|
def handle_signature(self, sig: str, signode: addnodes.desc_signature):
|
|
signode['fullname'] = sig
|
|
signode['tocname'] = tocname = sig.split('::')[-1]
|
|
signode += addnodes.desc_name(text=tocname)
|
|
return signode['fullname']
|
|
|
|
def add_target_and_index(
|
|
self,
|
|
name: str,
|
|
sig: str,
|
|
signode: addnodes.desc_signature
|
|
) -> None:
|
|
idx = ".".join(name.split("::"))
|
|
signode['ids'].append(idx)
|
|
if 'noindex' not in self.options:
|
|
tocname: str = signode.get('tocname', name)
|
|
objs = self.env.domaindata[self.domain]['objects']
|
|
# (name, sig, typ, docname, anchor, prio)
|
|
objs.append((name,
|
|
tocname,
|
|
type(self).name,
|
|
self.env.docname,
|
|
idx,
|
|
1))
|
|
|
|
class CellGroupedField(Field):
|
|
"""Custom version of GroupedField which doesn't require content."""
|
|
is_grouped = True
|
|
list_type = nodes.bullet_list
|
|
|
|
def __init__(self, name: str, names: tuple[str, ...] = (), label: str = None,
|
|
rolename: str = None, can_collapse: bool = False) -> None:
|
|
super().__init__(name, names, label, True, rolename)
|
|
self.can_collapse = can_collapse
|
|
|
|
def make_field(self, types: dict[str, list[Node]], domain: str,
|
|
items: tuple, env: BuildEnvironment = None,
|
|
inliner: Inliner = None, location: Node = None) -> nodes.field:
|
|
fieldname = nodes.field_name('', self.label)
|
|
listnode = self.list_type()
|
|
for fieldarg, content in items:
|
|
par = nodes.paragraph()
|
|
if fieldarg:
|
|
par.extend(self.make_xrefs(self.rolename, domain,
|
|
fieldarg, nodes.Text,
|
|
env=env, inliner=inliner, location=location))
|
|
|
|
if len(content) == 1 and (
|
|
isinstance(content[0], nodes.Text) or
|
|
(isinstance(content[0], nodes.inline) and len(content[0]) == 1 and
|
|
isinstance(content[0][0], nodes.Text))):
|
|
par += nodes.Text(' -- ')
|
|
par += content
|
|
listnode += nodes.list_item('', par)
|
|
|
|
if len(items) == 1 and self.can_collapse:
|
|
list_item = cast(nodes.list_item, listnode[0])
|
|
fieldbody = nodes.field_body('', list_item[0])
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
fieldbody = nodes.field_body('', listnode)
|
|
return nodes.field('', fieldname, fieldbody)
|
|
|
|
class CellNode(TocNode):
|
|
"""A custom node that describes an internal cell."""
|
|
|
|
name = 'cell'
|
|
|
|
option_spec = {
|
|
'title': directives.unchanged,
|
|
'ports': directives.unchanged,
|
|
'properties': directives.unchanged,
|
|
}
|
|
|
|
doc_field_types = [
|
|
CellGroupedField('props', label='Properties', rolename='prop',
|
|
names=('properties', 'property', 'tag', 'tags'),
|
|
can_collapse=True),
|
|
]
|
|
|
|
def handle_signature(self, sig: str, signode: addnodes.desc_signature):
|
|
signode['fullname'] = sig
|
|
signode['tocname'] = tocname = sig.split('::')[-1]
|
|
signode += addnodes.desc_addname(text="yosys> help ")
|
|
signode += addnodes.desc_name(text=tocname)
|
|
return signode['fullname']
|
|
|
|
def add_target_and_index(
|
|
self,
|
|
name: str,
|
|
sig: str,
|
|
signode: addnodes.desc_signature
|
|
) -> None:
|
|
idx = ".".join(name.split("::"))
|
|
signode['ids'].append(idx)
|
|
if 'noindex' not in self.options:
|
|
tocname: str = signode.get('tocname', name)
|
|
title: str = self.options.get('title', sig)
|
|
titlemap = self.env.domaindata[self.domain]['obj2title']
|
|
titlemap[name] = title
|
|
props = self.options.get('properties', '')
|
|
if props:
|
|
propmap = self.env.domaindata[self.domain]['obj2prop']
|
|
propmap[name] = props.split(' ')
|
|
objs = self.env.domaindata[self.domain]['objects']
|
|
# (name, sig, typ, docname, anchor, prio)
|
|
objs.append((name,
|
|
tocname,
|
|
type(self).name,
|
|
self.env.docname,
|
|
idx,
|
|
0))
|
|
|
|
def transform_content(self, contentnode: addnodes.desc_content) -> None:
|
|
# Add the cell title to the body
|
|
if 'title' in self.options:
|
|
titlenode = nodes.paragraph()
|
|
titlenode += nodes.strong()
|
|
titlenode[-1] += nodes.Text(self.options['title'])
|
|
contentnode.insert(0, titlenode)
|
|
|
|
class CellSourceNode(TocNode):
|
|
"""A custom code block for including cell source."""
|
|
|
|
name = 'cellsource'
|
|
|
|
option_spec = {
|
|
"source": directives.unchanged_required,
|
|
"language": directives.unchanged_required,
|
|
'lineno-start': int,
|
|
}
|
|
|
|
def handle_signature(
|
|
self,
|
|
sig,
|
|
signode: addnodes.desc_signature
|
|
) -> str:
|
|
language = self.options.get('language')
|
|
signode['fullname'] = sig
|
|
signode['tocname'] = f"{sig.split('::')[-2]} {language}"
|
|
signode += addnodes.desc_name(text="Simulation model")
|
|
signode += addnodes.desc_sig_space()
|
|
signode += addnodes.desc_addname(text=f'({language})')
|
|
return signode['fullname']
|
|
|
|
def run(self) -> list[Node]:
|
|
"""Override run to parse content as a code block"""
|
|
if ':' in self.name:
|
|
self.domain, self.objtype = self.name.split(':', 1)
|
|
else:
|
|
self.domain, self.objtype = '', self.name
|
|
self.indexnode = addnodes.index(entries=[])
|
|
|
|
node = addnodes.desc()
|
|
node.document = self.state.document
|
|
source, line = self.get_source_info()
|
|
if line is not None:
|
|
line -= 1
|
|
self.state.document.note_source(source, line)
|
|
node['domain'] = self.domain
|
|
# 'desctype' is a backwards compatible attribute
|
|
node['objtype'] = node['desctype'] = self.objtype
|
|
node['noindex'] = noindex = ('noindex' in self.options)
|
|
node['noindexentry'] = ('noindexentry' in self.options)
|
|
node['nocontentsentry'] = ('nocontentsentry' in self.options)
|
|
if self.domain:
|
|
node['classes'].append(self.domain)
|
|
node['classes'].append(node['objtype'])
|
|
|
|
self.names = []
|
|
signatures = self.get_signatures()
|
|
for sig in signatures:
|
|
# add a signature node for each signature in the current unit
|
|
# and add a reference target for it
|
|
signode = addnodes.desc_signature(sig, '')
|
|
self.set_source_info(signode)
|
|
node.append(signode)
|
|
try:
|
|
# name can also be a tuple, e.g. (classname, objname);
|
|
# this is strictly domain-specific (i.e. no assumptions may
|
|
# be made in this base class)
|
|
name = self.handle_signature(sig, signode)
|
|
except ValueError:
|
|
# signature parsing failed
|
|
signode.clear()
|
|
signode += addnodes.desc_name(sig, sig)
|
|
continue # we don't want an index entry here
|
|
finally:
|
|
# Private attributes for ToC generation. Will be modified or removed
|
|
# without notice.
|
|
if self.env.app.config.toc_object_entries:
|
|
signode['_toc_parts'] = self._object_hierarchy_parts(signode)
|
|
signode['_toc_name'] = self._toc_entry_name(signode)
|
|
else:
|
|
signode['_toc_parts'] = ()
|
|
signode['_toc_name'] = ''
|
|
if name not in self.names:
|
|
self.names.append(name)
|
|
if not noindex:
|
|
# only add target and index entry if this is the first
|
|
# description of the object with this name in this desc block
|
|
self.add_target_and_index(name, sig, signode)
|
|
|
|
# handle code
|
|
code = '\n'.join(self.content)
|
|
literal: Element = nodes.literal_block(code, code)
|
|
if 'lineno-start' in self.options:
|
|
literal['linenos'] = True
|
|
literal['highlight_args'] = {
|
|
'linenostart': self.options['lineno-start']
|
|
}
|
|
literal['classes'] += self.options.get('class', [])
|
|
literal['language'] = self.options.get('language')
|
|
literal = container_wrapper(self, literal, self.options.get('source'))
|
|
|
|
return [self.indexnode, node, literal]
|
|
|
|
class CellGroupNode(TocNode):
|
|
name = 'cellgroup'
|
|
|
|
option_spec = {
|
|
'caption': directives.unchanged,
|
|
}
|
|
|
|
def add_target_and_index(self, name: str, sig: str, signode: addnodes.desc_signature) -> None:
|
|
if self.options.get('caption', ''):
|
|
super().add_target_and_index(name, sig, signode)
|
|
|
|
def handle_signature(
|
|
self,
|
|
sig,
|
|
signode: addnodes.desc_signature
|
|
) -> str:
|
|
signode['fullname'] = fullname = sig
|
|
caption = self.options.get("caption", fullname)
|
|
if caption:
|
|
signode['tocname'] = caption
|
|
signode += addnodes.desc_name(text=caption)
|
|
return fullname
|
|
|
|
class TagIndex(Index):
|
|
"""A custom directive that creates a tag matrix."""
|
|
|
|
name = 'tag'
|
|
localname = 'Tag Index'
|
|
shortname = 'Tag'
|
|
|
|
def __init__(self, *args, **kwargs):
|
|
super(TagIndex, self).__init__(*args, **kwargs)
|
|
|
|
def generate(self, docnames=None):
|
|
"""Return entries for the index given by *name*. If *docnames* is
|
|
given, restrict to entries referring to these docnames.
|
|
The return value is a tuple of ``(content, collapse)``, where
|
|
* collapse* is a boolean that determines if sub-entries should
|
|
start collapsed (for output formats that support collapsing
|
|
sub-entries).
|
|
*content* is a sequence of ``(letter, entries)`` tuples, where *letter*
|
|
is the "heading" for the given *entries*, usually the starting letter.
|
|
*entries* is a sequence of single entries, where a single entry is a
|
|
sequence ``[name, subtype, docname, anchor, extra, qualifier, descr]``.
|
|
The items in this sequence have the following meaning:
|
|
- `name` -- the name of the index entry to be displayed
|
|
- `subtype` -- sub-entry related type:
|
|
0 -- normal entry
|
|
1 -- entry with sub-entries
|
|
2 -- sub-entry
|
|
- `docname` -- docname where the entry is located
|
|
- `anchor` -- anchor for the entry within `docname`
|
|
- `extra` -- extra info for the entry
|
|
- `qualifier` -- qualifier for the description
|
|
- `descr` -- description for the entry
|
|
Qualifier and description are not rendered e.g. in LaTeX output.
|
|
"""
|
|
|
|
content = {}
|
|
|
|
objs = {name: (dispname, typ, docname, anchor)
|
|
for name, dispname, typ, docname, anchor, prio
|
|
in self.domain.get_objects()}
|
|
|
|
tmap = {}
|
|
tags = self.domain.data[f'obj2{self.name}']
|
|
for name, tags in tags.items():
|
|
for tag in tags:
|
|
tmap.setdefault(tag,[])
|
|
tmap[tag].append(name)
|
|
|
|
for tag in tmap.keys():
|
|
lis = content.setdefault(tag, [])
|
|
objlis = tmap[tag]
|
|
for objname in objlis:
|
|
dispname, typ, docname, anchor = objs[objname]
|
|
lis.append((
|
|
dispname, 0, docname,
|
|
anchor,
|
|
docname, '', typ
|
|
))
|
|
ret = [(k, v) for k, v in sorted(content.items())]
|
|
|
|
return (ret, True)
|
|
|
|
class CommandIndex(Index):
|
|
name = 'cmd'
|
|
localname = 'Command Reference'
|
|
shortname = 'Command'
|
|
|
|
def __init__(self, *args, **kwargs):
|
|
super(CommandIndex, self).__init__(*args, **kwargs)
|
|
|
|
def generate(self, docnames=None):
|
|
"""Return entries for the index given by *name*. If *docnames* is
|
|
given, restrict to entries referring to these docnames.
|
|
The return value is a tuple of ``(content, collapse)``, where
|
|
* collapse* is a boolean that determines if sub-entries should
|
|
start collapsed (for output formats that support collapsing
|
|
sub-entries).
|
|
*content* is a sequence of ``(letter, entries)`` tuples, where *letter*
|
|
is the "heading" for the given *entries*, usually the starting letter.
|
|
*entries* is a sequence of single entries, where a single entry is a
|
|
sequence ``[name, subtype, docname, anchor, extra, qualifier, descr]``.
|
|
The items in this sequence have the following meaning:
|
|
- `name` -- the name of the index entry to be displayed
|
|
- `subtype` -- sub-entry related type:
|
|
0 -- normal entry
|
|
1 -- entry with sub-entries
|
|
2 -- sub-entry
|
|
- `docname` -- docname where the entry is located
|
|
- `anchor` -- anchor for the entry within `docname`
|
|
- `extra` -- extra info for the entry
|
|
- `qualifier` -- qualifier for the description
|
|
- `descr` -- description for the entry
|
|
Qualifier and description are not rendered e.g. in LaTeX output.
|
|
"""
|
|
|
|
content = {}
|
|
items = ((name, dispname, typ, docname, anchor)
|
|
for name, dispname, typ, docname, anchor, prio
|
|
in self.domain.get_objects()
|
|
if typ == self.name)
|
|
items = sorted(items, key=lambda item: item[0])
|
|
for name, dispname, typ, docname, anchor in items:
|
|
lis = content.setdefault(self.shortname, [])
|
|
lis.append((
|
|
dispname, 0, docname,
|
|
anchor,
|
|
'', '', typ
|
|
))
|
|
ret = [(k, v) for k, v in sorted(content.items())]
|
|
|
|
return (ret, True)
|
|
|
|
class CellIndex(CommandIndex):
|
|
name = 'cell'
|
|
localname = 'Internal cell reference'
|
|
shortname = 'Internal cell'
|
|
|
|
class PropIndex(TagIndex):
|
|
"""A custom directive that creates a properties matrix."""
|
|
|
|
name = 'prop'
|
|
localname = 'Property Index'
|
|
shortname = 'Prop'
|
|
fieldname = 'props'
|
|
|
|
def generate(self, docnames=None):
|
|
content = {}
|
|
|
|
cells = {name: (dispname, docname, anchor)
|
|
for name, dispname, typ, docname, anchor, _
|
|
in self.domain.get_objects()
|
|
if typ == 'cell'}
|
|
props = {name: (dispname, docname, anchor)
|
|
for name, dispname, typ, docname, anchor, _
|
|
in self.domain.get_objects()
|
|
if typ == 'prop'}
|
|
|
|
tmap: dict[str, list[str]] = {}
|
|
tags: dict[str, list[str]] = self.domain.data[f'obj2{self.name}']
|
|
for name, tags in tags.items():
|
|
for tag in tags:
|
|
tmap.setdefault(tag,[])
|
|
tmap[tag].append(name)
|
|
|
|
for tag in sorted(tmap.keys()):
|
|
test = re.match(r'^(\w+[_-])', tag)
|
|
tag_prefix = test.group(1)
|
|
lis = content.setdefault(tag_prefix, [])
|
|
try:
|
|
dispname, docname, anchor = props[tag]
|
|
except KeyError:
|
|
dispname = tag
|
|
docname = anchor = ''
|
|
lis.append((
|
|
dispname, 1, docname,
|
|
anchor,
|
|
'', '', docname or 'unavailable'
|
|
))
|
|
objlis = tmap[tag]
|
|
for objname in sorted(objlis):
|
|
dispname, docname, anchor = cells[objname]
|
|
lis.append((
|
|
dispname, 2, docname,
|
|
anchor,
|
|
'', '', docname
|
|
))
|
|
ret = [(k, v) for k, v in sorted(content.items())]
|
|
|
|
return (ret, True)
|
|
|
|
class TitleRefRole(XRefRole):
|
|
"""XRefRole used which has the cmd title as the displayed text."""
|
|
pass
|
|
|
|
class CommandDomain(Domain):
|
|
name = 'cmd'
|
|
label = 'Yosys commands'
|
|
|
|
roles = {
|
|
'ref': XRefRole(),
|
|
'title': TitleRefRole(),
|
|
}
|
|
|
|
directives = {
|
|
'def': CommandNode,
|
|
'usage': CommandUsageNode,
|
|
'optiongroup': CommandOptionGroupNode,
|
|
}
|
|
|
|
indices = {
|
|
CommandIndex,
|
|
TagIndex
|
|
}
|
|
|
|
initial_data = {
|
|
'objects': [], # object list
|
|
'obj2tag': {}, # name -> tags
|
|
'obj2title': {}, # name -> title
|
|
}
|
|
|
|
def get_full_qualified_name(self, node):
|
|
"""Return full qualified name for a given node"""
|
|
return "{}.{}.{}".format(type(self).name,
|
|
type(node).__name__,
|
|
node.arguments[0])
|
|
|
|
def get_objects(self):
|
|
for obj in self.data['objects']:
|
|
yield(obj)
|
|
|
|
def resolve_xref(self, env, fromdocname, builder, typ,
|
|
target, node, contnode):
|
|
|
|
match = [(docname, anchor, name)
|
|
for name, sig, typ, docname, anchor, prio
|
|
in self.get_objects() if sig == target]
|
|
|
|
if match:
|
|
todocname = match[0][0]
|
|
targ = match[0][1]
|
|
qual_name = match[0][2]
|
|
title = self.data['obj2title'].get(qual_name, targ)
|
|
|
|
if typ == 'title':
|
|
# caller wants the title in the content of the node
|
|
cmd = contnode.astext()
|
|
contnode = Text(f'{cmd} - {title}')
|
|
return make_refnode(builder, fromdocname, todocname,
|
|
targ, contnode)
|
|
else:
|
|
# cmd title as hover text
|
|
return make_refnode(builder, fromdocname, todocname,
|
|
targ, contnode, title)
|
|
else:
|
|
print(f"Missing ref for {target} in {fromdocname} ")
|
|
return None
|
|
|
|
class CellDomain(CommandDomain):
|
|
name = 'cell'
|
|
label = 'Yosys internal cells'
|
|
|
|
roles = CommandDomain.roles.copy()
|
|
roles.update({
|
|
'prop': XRefRole()
|
|
})
|
|
|
|
directives = {
|
|
'def': CellNode,
|
|
'defprop': PropNode,
|
|
'source': CellSourceNode,
|
|
'group': CellGroupNode,
|
|
}
|
|
|
|
indices = {
|
|
CellIndex,
|
|
PropIndex
|
|
}
|
|
|
|
initial_data = {
|
|
'objects': [], # object list
|
|
'obj2prop': {}, # name -> properties
|
|
'obj2title': {}, # name -> title
|
|
}
|
|
|
|
def get_objects(self):
|
|
for obj in self.data['objects']:
|
|
yield(obj)
|
|
|
|
def autoref(name, rawtext: str, text: str, lineno, inliner: Inliner,
|
|
options=None, content=None):
|
|
words = text.split(' ')
|
|
if len(words) == 2 and words[0] == "help":
|
|
IsLinkable = True
|
|
thing = words[1]
|
|
else:
|
|
IsLinkable = len(words) == 1 and words[0][0] != '-'
|
|
thing = words[0]
|
|
if IsLinkable:
|
|
role = 'cell:ref' if thing[0] == '$' else 'cmd:ref'
|
|
text = f'{text} <{thing}>'
|
|
else:
|
|
role = 'yoscrypt'
|
|
return inliner.interpreted(rawtext, text, role, lineno)
|
|
|
|
def setup(app: Sphinx):
|
|
app.add_domain(CommandDomain)
|
|
app.add_domain(CellDomain)
|
|
|
|
StandardDomain.initial_data['labels']['commandindex'] =\
|
|
('cmd-cmd', '', 'Command Reference')
|
|
StandardDomain.initial_data['labels']['tagindex'] =\
|
|
('cmd-tag', '', 'Tag Index')
|
|
StandardDomain.initial_data['labels']['cellindex'] =\
|
|
('cell-cell', '', 'Internal cell reference')
|
|
StandardDomain.initial_data['labels']['propindex'] =\
|
|
('cell-prop', '', 'Property Index')
|
|
|
|
StandardDomain.initial_data['anonlabels']['commandindex'] =\
|
|
('cmd-cmd', '')
|
|
StandardDomain.initial_data['anonlabels']['tagindex'] =\
|
|
('cmd-tag', '')
|
|
StandardDomain.initial_data['anonlabels']['cellindex'] =\
|
|
('cell-cell', '')
|
|
StandardDomain.initial_data['anonlabels']['propindex'] =\
|
|
('cell-prop', '')
|
|
|
|
app.add_role('autoref', autoref)
|
|
|
|
return {
|
|
'version': '0.3',
|
|
'parallel_read_safe': False,
|
|
}
|