mirror of
https://github.com/YosysHQ/yosys
synced 2025-04-25 10:05:33 +00:00
cmdref: Drop optiongroups
Linking to optiongroups doesn't add *that* much, and is kind of a pain; meanwhile having the optiongroups adds an extra level of indentation. Instead of options needing to be in an option group, they instead go in either the root node or nested in a usage node. Putting them in a usage node allows for more-or-less the previous behaviour but without making it the default.
This commit is contained in:
Krystine Sherwin
parent
a2433ba34b
commit
ebd6d5f85b
7 changed files with 117 additions and 148 deletions
|
|
@ -365,14 +365,14 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
|
|||
def render(content_list: YosysCmdContentListing, indent: int=0):
|
||||
content_source = content_list.source_file or source_name
|
||||
indent_str = ' '*indent
|
||||
if content_list.type in ['usage', 'optiongroup']:
|
||||
if content_list.type == 'usage':
|
||||
if content_list.body:
|
||||
self.add_line(f'{indent_str}.. {domain}:{content_list.type}:: {self.name}::{content_list.body}', content_source)
|
||||
else:
|
||||
self.add_line(f'{indent_str}.. {domain}:{content_list.type}:: {self.name}::', content_source)
|
||||
self.add_line(f'{indent_str} :noindex:', source_name)
|
||||
self.add_line('', source_name)
|
||||
elif content_list.type in ['option']:
|
||||
elif content_list.type == 'option':
|
||||
self.add_line(f'{indent_str}:{content_list.type} {content_list.body}:', content_source)
|
||||
elif content_list.type == 'text':
|
||||
self.add_line(f'{indent_str}{content_list.body}', content_source)
|
||||
|
|
|
|||
|
|
@ -58,101 +58,12 @@ class TocNode(ObjectDescription):
|
|||
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
|
||||
})
|
||||
class NodeWithOptions(TocNode):
|
||||
"""A custom node with options."""
|
||||
|
||||
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 with yoscrypt highlighting"""
|
||||
|
|
@ -186,6 +97,83 @@ class CommandOptionGroupNode(CommandUsageNode):
|
|||
newchildren.append(newnode)
|
||||
contentnode.children = newchildren
|
||||
|
||||
class CommandNode(NodeWithOptions):
|
||||
"""A custom node that describes a command."""
|
||||
|
||||
name = 'cmd'
|
||||
required_arguments = 1
|
||||
|
||||
option_spec = NodeWithOptions.option_spec.copy()
|
||||
option_spec.update({
|
||||
'title': directives.unchanged,
|
||||
'tags': directives.unchanged
|
||||
})
|
||||
|
||||
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(NodeWithOptions):
|
||||
"""A custom node that describes command usages"""
|
||||
|
||||
name = 'cmdusage'
|
||||
|
||||
option_spec = NodeWithOptions.option_spec
|
||||
option_spec.update({
|
||||
'usage': directives.unchanged,
|
||||
})
|
||||
|
||||
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 PropNode(TocNode):
|
||||
name = 'prop'
|
||||
fieldname = 'props'
|
||||
|
|
@ -621,7 +609,6 @@ class CommandDomain(Domain):
|
|||
directives = {
|
||||
'def': CommandNode,
|
||||
'usage': CommandUsageNode,
|
||||
'optiongroup': CommandOptionGroupNode,
|
||||
}
|
||||
|
||||
indices = {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue