# Copyright 2020, Red Hat, Inc. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. You may obtain # a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. """Display extra specs in documentation. Provides a single directive that can be used to list all extra specs validators and, thus, document all extra specs that nova recognizes and supports. """ import typing as ty from docutils import nodes from docutils.parsers import rst from docutils.parsers.rst import directives from docutils import statemachine from sphinx import addnodes from sphinx import directives as sphinx_directives from sphinx import domains from sphinx import roles from sphinx.util import logging from sphinx.util import nodes as sphinx_nodes from nova.api.validation.extra_specs import base from nova.api.validation.extra_specs import validators LOG = logging.getLogger(__name__) class ExtraSpecXRefRole(roles.XRefRole): """Cross reference a extra spec. Example:: :nova:extra-spec:`hw:cpu_policy` """ def __init__(self): super(ExtraSpecXRefRole, self).__init__( warn_dangling=True, ) def process_link(self, env, refnode, has_explicit_title, title, target): # The anchor for the extra spec link is the extra spec name return target, target class ExtraSpecDirective(sphinx_directives.ObjectDescription): """Document an individual extra spec. Accepts one required argument - the extra spec name, including the group. Example:: .. extra-spec:: hw:cpu_policy """ def handle_signature(self, sig, signode): """Transform an option description into RST nodes.""" # Insert a node into the output showing the extra spec name signode += addnodes.desc_name(sig, sig) signode['allnames'] = [sig] return sig def add_target_and_index(self, firstname, sig, signode): cached_options = self.env.domaindata['nova']['extra_specs'] signode['ids'].append(sig) self.state.document.note_explicit_target(signode) # Store the location of the option definition for later use in # resolving cross-references cached_options[sig] = self.env.docname def _indent(text): if not text: return text padding = ' ' * 4 return padding + text def _format_validator_group_help( validators: ty.Dict[str, base.ExtraSpecValidator], summary: bool, ): """Generate reStructuredText snippets for a group of validators.""" for validator in validators.values(): for line in _format_validator_help(validator, summary): yield line def _format_validator_help( validator: base.ExtraSpecValidator, summary: bool, ): """Generate reStucturedText snippets for the provided validator. :param validator: A validator to document. :type validator: nova.api.validation.extra_specs.base.ExtraSpecValidator """ yield f'.. nova:extra-spec:: {validator.name}' yield '' # NOTE(stephenfin): We don't print the pattern, if present, since it's too # internal. Instead, the description should provide this information in a # human-readable format yield _indent(f':Type: {validator.value["type"].__name__}') if validator.value.get('min') is not None: yield _indent(f':Min: {validator.value["min"]}') if validator.value.get('max') is not None: yield _indent(f':Max: {validator.value["max"]}') yield '' if not summary: for line in validator.description.splitlines(): yield _indent(line) yield '' if validator.deprecated: yield _indent('.. warning::') yield _indent( 'This extra spec has been deprecated and should not be used.' ) yield '' class ExtraSpecGroupDirective(rst.Directive): """Document extra specs belonging to the specified group. Accepts one optional argument - the extra spec group - and one option - whether to show a summary view only (omit descriptions). Example:: .. extra-specs:: hw_rng :summary: """ required_arguments = 0 optional_arguments = 1 option_spec = { 'summary': directives.flag, } has_content = False def run(self): result = statemachine.ViewList() source_name = self.state.document.current_source group = self.arguments[0] if self.arguments else None summary = self.options.get('summary', False) if group: group_validators = { n.split(':', 1)[1]: v for n, v in validators.VALIDATORS.items() if ':' in n and n.split(':', 1)[0].split('{')[0] == group } else: group_validators = { n: v for n, v in validators.VALIDATORS.items() if ':' not in n } if not group_validators: LOG.warning("No validators found for group '%s'", group or '') for count, line in enumerate( _format_validator_group_help(group_validators, summary) ): result.append(line, source_name, count) LOG.debug('%5d%s%s', count, ' ' if line else '', line) node = nodes.section() node.document = self.state.document sphinx_nodes.nested_parse_with_titles(self.state, result, node) return node.children class NovaDomain(domains.Domain): """nova domain.""" name = 'nova' label = 'nova' object_types = { 'configoption': domains.ObjType( 'extra spec', 'spec', ), } directives = { 'extra-spec': ExtraSpecDirective, } roles = { 'extra-spec': ExtraSpecXRefRole(), } initial_data = { 'extra_specs': {}, } def resolve_xref( self, env, fromdocname, builder, typ, target, node, contnode, ): """Resolve cross-references""" if typ == 'option': return sphinx_nodes.make_refnode( builder, fromdocname, env.domaindata['nova']['extra_specs'][target], target, contnode, target, ) return None def setup(app): app.add_domain(NovaDomain) app.add_directive('extra-specs', ExtraSpecGroupDirective)