mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-22 16:45:32 +00:00
Code Activity

cmdref: Drop optiongroups

Browse source 
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 2025-03-21 10:28:48 +13:00
parent a2433ba34b
commit ebd6d5f85b
No known key found for this signature in database
7 changed files with 117 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/source/cmd/index_internal.rst
View file

@ -53,21 +53,13 @@ The ``formatted_help()`` method
dash (``-``); takes an optional second argument which adds a paragraph
node as a means of description
+ ``ContentListing::open_optiongroup``
* each option must be in an optiongroup
* optional name argument, which will be rendered in (RST) output
+ ``ContentListing::open_usage`` creates and returns a new usage node, can be
used to e.g. add text/options specific to a given usage of the command
+ ``ContentListing::open_option`` creates and returns a new option node, can
be used to e.g. add multiple paragraphs to an option's description
+ paragraphs are treated as raw RST, allowing for inline formatting and
references as if it were written in the RST file itself
.. todo:: Support anonymous optiongroup
If an option is added to the root node it should add the option to the last
child of the root, making a new child if the last child is not an optiongroup
.. literalinclude:: /generated/chformal.cc
:language: c++
:start-at: bool formatted_help()
@ -88,7 +80,7 @@ Dumping command help to json
* if a line is indented and starts with a dash (``-``), it is parsed as an
option
* anything else is parsed as a codeblock and added to either the root node
or the current option/optiongroup depending on the indentation
or the current option depending on the indentation
+ dictionary of command name to ``ContentListing``

4
docs/util/cmd_documenter.py
View file

@ -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)

171
docs/util/custom_directives.py
View file

@ -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 = {