# Copyright (C) British Crown (Met Office) & Contributors.
# This file is part of Rose, a framework for meteorological suites.
#
# Rose is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Rose is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Rose. If not, see <http://www.gnu.org/licenses/>.
# -----------------------------------------------------------------------------
"""The Rose domain is for documenting Rose configurations and built-in
applications.
Rose Objects:
The Rose domain supports the following object types:
* ``rose:app`` - Rose Applications.
* ``rose:file`` - Root Rose configurations.
* ``rose:conf`` - Rose configurations. Nest them to create configuration
sections.
See the corresponding directives for more information on each object type.
Reference Syntax:
Once documented, objects can be referenced using the following syntax:
.. code-block:: none
:rose:CONFIG-FILE[parent-section]child-config
:rose:CONFIG-FILE|top-level-config
Where ``CONFIG-FILE`` is:
* The ``APP-NAME`` for applications (e.g. ``fcm_make``).
* The ``FILE-NAME`` for configuration files (e.g. ``rose.conf``).
Referencing From RST Files:
To reference a Rose object add the object ``TYPE`` into the domain
(e.g. ``conf`` or ``app``).
.. code-block:: rst
:rose:TYPE:`CONFIG-FILE[parent-section]child-config`
e.g:
.. code-block:: rst
* :rose:app:`fcm_make`
* :rose:conf:`fcm_make.args`
Autodocumentation:
Documentation can be auto-built from RST formatted comments in Rose
configuration files using the ``autoconfig`` directive.
Note that due to the implementation of :py:mod:`metomi.rose.config` the
autodocumenter will represent empty sections as top level configuration
nodes.
Example:
.. code-block:: rst
.. rose:file:: rose-suite.conf
The config file used for configuring suite level settings.
.. rose:conf:: jinja2:suite.rc
A section for specifying Jinja2 settings for use in the
``flow.cylc`` file.
Note that one ommits the square brackets for config sections. If
:rose:conf: contains other :rose:conf:'s then it is implicitly a
section and the brackets are added automatically. If you wish to
document a section which contains no settings write it using
square brackets.
.. rose:conf:: ROSE_VERSION
provide the intended Rose version to the suite.
.. deprecated:: 6.1.0
No longer required, this context is now provided internally.
.. rose:conf:: CYLC_VERSION
provide the intended Rose version to the suite.
.. deprecated:: 6.1.0
See :rose:conf:`ROSE_VERSION`.
.. ^ relative reference
Referencing Objects Via Intersphinx:
Reference Rose objects as you would any other e.g:
.. code-block:: rst
:rose:file:`intersphinx-mapping:rose-app.conf`
A quick way to get the object reference is to extract if from the URL.
For example in the following URL:
.. code-block:: none
doc-root/api/configuration/application.html#rose:file:rose-app.conf
The reference is ``rose:file:rose-app.conf``.
"""
import re
from docutils.nodes import block_quote
from docutils.parsers.rst import Directive
from docutils.statemachine import StringList
from sphinx import addnodes
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, ObjType
from sphinx.roles import XRefRole
from sphinx.util import logging
from sphinx.util.docfields import Field, TypedField
from sphinx.util.nodes import make_refnode
from metomi.rose import config
LOGGER = logging.getLogger(__name__)
ROSE_DOMAIN_REGEX = re.compile( # Regex for a fully qualified Rose domain.
r'rose:(\w+):' # Rose domain prefix + object type.
r'([^\|\[ \n]+)' # Configuration file.
r'(\[.*\])?' # Configuration section.
r'(?:\|?(.*))?' # Configuration setting.
)
SECTION_REGEX = re.compile( # Regex for splitting sections and settings.
r'(\[.*\])(.*)'
)
OPT_ARG_REGEX = re.compile( # Regex for splitting domains and arguments
r'(^(?:[^\[\|=]+)?' # Configuration file.
r'(?:\[[^\]]+\])?' # Configuration section.
r'(?:[^=]+)?)' # Configuration setting.
r'(?:=(.*))?$' # Argument.
)
CROSS_DOMAIN_REGEX = re.compile( # Catch leading target from inter-sphinx ref.
r'^([\w\-]+)' # inter-sphinx mapping
r':' # colon divider
r'([\w\-].*)$' # rose object reference
)
def tokenise_namespace(namespace):
"""Convert a namespace string into a list of tokens.
Tokens are (domain, name) tuples.
Examples:
# Partial namespaces.
>>> tokenise_namespace('rose:conf:foo')
[('rose:conf', 'foo')]
>>> tokenise_namespace('rose:conf:[foo]')
[('rose:conf', '[foo]')]
>>> tokenise_namespace('rose:conf:[foo]bar')
[('rose:conf', '[foo]'), ('rose:conf', 'bar')]
# Full namespaces.
>>> tokenise_namespace('rose:app:foo')
[('rose:app', 'foo')]
>>> tokenise_namespace('rose:file:foo.conf')
[('rose:file', 'foo.conf')]
>>> tokenise_namespace('rose:conf:foo|bar')
[('rose:app', 'foo'), ('rose:conf', 'bar')]
>>> tokenise_namespace('rose:conf:foo[bar]')
[('rose:app', 'foo'), ('rose:conf', '[bar]')]
>>> tokenise_namespace('rose:conf:foo[bar]baz')
[('rose:app', 'foo'), ('rose:conf', '[bar]'), ('rose:conf', 'baz')]
>>> tokenise_namespace('rose:conf:foo.conf[bar:pub]baz'
... ) # doctest: +NORMALIZE_WHITESPACE
[('rose:file', 'foo.conf'), ('rose:conf', '[bar:pub]'),
('rose:conf', 'baz')]
"""
match = ROSE_DOMAIN_REGEX.match(namespace)
domain = ':'.join(namespace.split(':')[2:])
if not match:
# Namespace is only partial, return it as a single configuration token.
section, setting = SECTION_REGEX.match(domain).groups()
ret = [('rose:conf', section)]
if setting:
ret.append(('rose:conf', setting))
return ret
typ, conf_file, conf_section, setting = match.groups()
if typ == 'conf' and not (conf_section or setting):
# Namespace is only partial, return it as a single configuration token.
return [(('rose:conf'), domain)]
if typ in ['file', 'app']:
ret = [('rose:%s' % typ, conf_file)]
elif '.' in conf_file:
# Must be a Rose config file.
ret = [('rose:file', conf_file)]
else:
# Must be a Rose application.
ret = [('rose:app', conf_file)]
if conf_section:
ret.append(('rose:conf', conf_section))
if setting:
ret.append(('rose:conf', setting))
return ret
def namespace_from_tokens(tokens):
"""Convert a list of tokens into a string namespace.
Tokens are (domain, name) tuples.
Examples:
>>> namespace_from_tokens([('rose:app', 'foo')])
'rose:app:foo'
>>> namespace_from_tokens([('rose:file', 'foo')])
'rose:file:foo'
>>> namespace_from_tokens([('rose:app', 'foo'), ('rose:conf', 'bar')])
'rose:conf:foo|bar'
>>> namespace_from_tokens([('rose:app', 'foo'), ('rose:conf', '[bar]')])
'rose:conf:foo[bar]'
>>> namespace_from_tokens([('rose:app', 'foo'), ('rose:conf', '[bar]'),
... ('rose:conf', 'baz')])
'rose:conf:foo[bar]baz'
>>> namespace_from_tokens([('rose:file', 'foo.conf'),
... ('rose:conf', '[bar]'),
... ('rose:conf', 'baz')])
'rose:conf:foo.conf[bar]baz'
"""
ret = tokens[-1][0] + ':'
previous_domain = None
for domain, name in tokens:
# Root level configuration files.
if domain in ['rose:app', 'rose:file']:
if previous_domain:
# App must be a root domain.
LOGGER.warning('Invalid tokens "%s"' % tokens)
return False
else:
ret += name
# Rose configuration.
elif domain == 'rose:conf':
if previous_domain in ['rose:app', 'rose:file']:
if name.startswith('['):
# section requires no separator
ret += name
else:
# Setting requires `|` separator.
ret += '|%s' % name
elif previous_domain == 'rose:conf':
# Setting requires no separator if following a section.
ret += name
else:
LOGGER.warning('Invalid tokens "%s"' % tokens)
return False
else:
LOGGER.warning('Invalid tokens "%s"' % tokens)
return False
previous_domain = domain
return ret
TOKEN_ORDER = [
('rose:file', 'rose:file'),
('rose:app', 'rose:app'),
('rose:conf-section', 'rose:conf'),
('rose:conf', 'rose:conf'),
]
def tokens_from_ref_context(ref_context):
"""Extract a list of tokens from a ref_context dictionary.
Examples:
>>> tokens_from_ref_context({'rose:conf-section': '[bar]',
... 'rose:conf': 'baz',
... 'rose:file': 'foo'})
[('rose:file', 'foo'), ('rose:conf', '[bar]'), ('rose:conf', 'baz')]
>>> tokens_from_ref_context({'rose:conf-section': '[bar]',
... 'rose:conf': 'baz',
... 'rose:app': 'foo'})
[('rose:app', 'foo'), ('rose:conf', '[bar]'), ('rose:conf', 'baz')]
"""
# Generate context namespace from ref_context.
ret = [(v, ref_context[k]) for k, v in TOKEN_ORDER if k in ref_context]
# Remove any duplicate items (happens for conf-sections where you
# may get {'rose:conf-section': '[foo]', 'rose:conf': '[foo]'}.
last = None
for item in list(ret):
if last is not None and item == last:
ret.remove(item)
last = item
return ret
[docs]
class RoseDirective(ObjectDescription):
"""Base class for implementing Rose objects.
Subclasses must provide:
- ``NAME``
Subclasses can provide:
- ``LABEL``
- ``ARGUMENT_SEPARATOR`` & ``ARGUMENT_REGEX``
- ``ALT_FORM_SEPARATOR``
- ``ALT_FORM_TEMPLATE``
- ``doc_field_types`` - List of ``Field`` objects for object
parameters.
- ``run()`` - For adding special rev_context variables via
``add_rev_context``.
- ``handle_signature()`` - For changing the display of objects.
- ``custom_name_template`` - String template accepting one string
format argument for custom formatting the node name (e.g. ``'[%s]'``
for conf sections).
ref_context Variables:
Sphinx domains use ``ref_context`` variables to determine the
relationship between objects. E.g. for a Rose app the ``rose:app``
variable is set to the name of the app. This variable will be made
available to all children which is how they determine that they belong
to the app.
* Variables set in ``run()`` are available to this object along with
all of its children.
* Variables set in ``before_content()`` are only available to children.
* All variables set via ``add_ref_context()`` will be automatically
removed in ``after_content()`` to prevent leaking scope.
"""
allow_nesting = False
"""Override in settings which are permitted to be nested (e.g. 'conf')."""
NAME = None
"""The Rose domain this directive implements, see RoseDomain.directives"""
LABEL = ''
"""Label to prepend to objects."""
ARGUMENT_SEPARATOR = None
"""String for separating the configuration name and argument."""
ARGUMENT_REGEX = None
"""Regex for splitting the directive name and argument."""
ALT_FORM_SEPARATOR = '&'
"""String for splitting alternate names."""
ALT_FORM_TEMPLATE = '(alternate: %s)'
"""String template for writing out alternate names. Takes one string format
argument."""
ROSE_CONTEXT = 'rose:%s'
"""Prefix for all Rose ref_context variables."""
def __init__(self, *args, **kwargs):
self.ref_context_to_remove = [] # Cannot do this in run().
self.registered_children = []
ObjectDescription.__init__(self, *args, **kwargs)
def run(self):
# Automatically generate the "rose:NAME" ref_context variable.
self.add_ref_context(self.NAME)
index_node, cont_node = ObjectDescription.run(self)
# Add a marker on the output node so we can determine the context
# namespace later (see RoseDomain.resolve_xref).
context_var = self.ROSE_CONTEXT % self.NAME
cont_node.ref_context = {
context_var: self.process_name(self.arguments[0].strip())[0]
}
# Add children if initialised via python - see RoseAutoDirective.
block = block_quote() # Create indented section.
for child_node in self.registered_children:
block.append(child_node) # Add child node to indented section.
cont_node.append(block) # Add indented section to this node.
return [index_node, cont_node]
def register_subnode(self, subnode):
"""Register a sub-configuration when creating Rose objects with Python.
Special method for the RoseDirective to facilitate building Rose domain
objects using the Python API rather than RST.
See :py:meth:`RoseAutoDirective.run` for usage example.
"""
self.registered_children.append(subnode)
def add_ref_context(self, key):
"""Add a new ``ref_context`` variable.
* The variable will be set to the name of the object.
* The variable will be automatically removed in ``after_content()``
to prevent leaking scope.
Args:
key (str): The name for the new variable without the ``rose:``
prefix.
"""
ref_context = self.state.document.settings.env.ref_context
context_var = self.ROSE_CONTEXT % key
ref_context[context_var] = self.process_name(
self.arguments[0].strip()
)[0]
self.ref_context_to_remove.append(key)
def remove_ref_context(self, key):
"""Remove a ``ref_context`` variable.
Args:
key (str): The name of the variable to remove without the
``rose:`` prefix.
"""
ref_context = self.state.document.settings.env.ref_context
context_var = self.ROSE_CONTEXT % key
if ref_context.get(context_var) == (
self.process_name(self.arguments[0].strip())[0]
):
del ref_context[context_var]
def get_ref_context(self, key):
"""Return the value of a ``ref_context`` variable.
Args:
key (str): The name of the variable without the ``rose:`` prefix.
Return:
The value of the context variable, if set via ``add_ref_context()``
this will be the name of the object which set it.
"""
ref_context = self.state.document.settings.env.ref_context
return ref_context.get(self.ROSE_CONTEXT % key)
def after_content(self):
"""This method is called after child objects have been processed.
There is also the ``before_content()`` method which is called during
``run()`` before child objects have been processed but after the
current object has been processed.
"""
for ind, child_node in enumerate(self.registered_children):
self.registered_children[ind] = child_node.run()[1]
for context_var in self.ref_context_to_remove:
self.remove_ref_context(context_var)
ObjectDescription.after_content(self)
def process_name(self, name):
"""Perform standard pre-processing of a node name.
* Process argument strings (e.g. ``bar`` in ``foo=bar``).
* Process alternate forms (e.g. ``bar`` in ``foo & bar``).
* Process custom name templates.
Return:
tuple - (name, argument, alt_forms)
- name (str) - The processed name with everything else
stripped.
- argument (str) - Any specified argument string else ''.
- alt_forms (list) - List of strings containing alternate names
for the node.
"""
alt_forms = []
if self.ALT_FORM_SEPARATOR:
ret = name.split(self.ALT_FORM_SEPARATOR)
name = ret[0].strip()
alt_forms = [x.strip() for x in ret[1:]]
# Separate argument strings (e.g. foo=FOO).
argument = ''
if self.ARGUMENT_REGEX:
try:
name, argument = self.ARGUMENT_REGEX.search(name).groups()
except ValueError:
pass
# Apply custom name template if specified.
if hasattr(self, 'custom_name_template'):
name = self.custom_name_template % name
return name, argument, alt_forms
def handle_signature(self, sig, signode, display_text=None):
"""This method determines the appearance of the object.
Overloaded Args:
display_test: Used for overriding the object name.
"""
# Override sig with display_text if provided.
if display_text is None:
display_text = sig
display_text, argument, alt_forms = self.process_name(display_text)
# Add a label before the name of the object.
signode += addnodes.desc_annotation(*('%s ' % self.LABEL,) * 2)
# Add the object name.
signode += addnodes.desc_name(sig, display_text)
# Add arguments.
if argument:
argument = '%s %s' % (self.ARGUMENT_SEPARATOR, argument)
signode += addnodes.desc_annotation(argument, argument)
# Add alternate object names.
if alt_forms:
signode += addnodes.desc_annotation(
*(self.ALT_FORM_TEMPLATE % (', '.join(alt_forms)),) * 2
)
signode['fullname'] = sig
return (sig, self.NAME, sig)
def needs_arglist(self):
return False
def add_target_and_index(self, name_cls, _, signode):
"""This method handles namespacing."""
name = self.process_name(name_cls[0])[0]
# Get the current context in tokenised form.
context_tokens = []
ref_context = self.state.document.settings.env.ref_context
for key in ['app', 'file', 'conf-section', 'conf']:
token = self.ROSE_CONTEXT % key
if token in ref_context:
value = ref_context[token]
if key == 'conf-section':
token = self.ROSE_CONTEXT % 'conf'
new_token = (token, value)
if new_token not in context_tokens:
context_tokens.append(new_token)
# Add a token representing the current node.
new_token = (self.ROSE_CONTEXT % self.NAME, name)
if new_token not in context_tokens:
context_tokens.append(new_token)
# Generate a namespace from the tokens.
namespace = namespace_from_tokens(context_tokens)
if namespace is False:
LOGGER.error(
'Invalid namespace for Rose object "%s"' % namespace,
location=signode,
)
# Register this namespace.
signode['ids'].append(namespace)
self.env.domaindata['rose']['objects'][namespace] = (
self.env.docname,
'',
)
def get_index_text(self, modname, name):
return ''
[docs]
class RoseAppDirective(RoseDirective):
"""Directive for documenting Rose apps.
Example:
Click :guilabel:`source` to view source code.
.. code-block:: rst
.. rose:app:: foo
An app called ``foo``.
"""
NAME = 'app'
LABEL = 'Rose App'
[docs]
class RoseFileDirective(RoseDirective):
"""Directive for documenting Rose files.
Example:
Click :guilabel:`source` to view source code.
.. code-block:: rst
.. rose:file:: foo
An configuration file called ``foo``.
"""
NAME = 'file'
LABEL = 'Rose Configuration'
[docs]
class RoseConfigDirective(RoseDirective):
"""Directive for documenting config sections.
Optional Attributes:
* ``envvar`` - Associate an environment variable with this
configuration option.
* ``compulsory`` - Set to ``True`` for compulsory settings, omit this
field for optional settings.
Additional ref_context:
* ``rose:conf-section`` - Set for parent configurations, is available
to any child nodes.
Example:
Click :guilabel:`source` to view source code.
.. code-block:: rst
.. rose:conf:: foo
:default: foo
:opt argtype foo: Description of option ``foo``.
:opt bar: Description of bar
A setting called ``foo``.
.. rose:conf:: bar
A section called ``bar``.
.. rose:conf:: baz
:compulsory: True
:env: AN_ASSOCIATED_ENVIRONMENT_VARIABLE
A config called ``[bar]baz``.
"""
NAME = 'conf'
LABEL = 'Config'
SECTION_REF_CONTEXT = 'conf-section'
ARGUMENT_REGEX = OPT_ARG_REGEX
ARGUMENT_SEPARATOR = '='
# Add custom fields.
doc_field_types = [
# NOTE: The field label must be sort to avoid causing a line break.
Field(
'envvar',
label='Env Var',
has_arg=False,
names=('env',),
bodyrolename='obj',
),
Field(
'compulsory',
label='Compulsory',
has_arg=True,
names=('compulsory',),
),
Field('default', label='Default', has_arg=False, names=('default',)),
TypedField(
'option',
label='Options',
names=('opt',),
typerolename='obj',
typenames=('paramtype', 'type'),
can_collapse=True,
),
]
def run(self):
"""Overridden to add the :rose:conf-section: ``ref_context`` variable
for nested sections."""
if self.registered_children or any(
'.. rose:conf::' in line for line in self.content
):
# This configuration contains other configurations i.e. it is a
# configuration section. Apply a custom_name_template so that it is
# written inside square brackets.
self.custom_name_template = '[%s]'
# Sections cannot be written with argument examples.
self.ARGUMENT_SEPARATOR = None
self.ARGUMENT_REGEX = None
# Add a ref_context variable to mark this node as a config section.
self.add_ref_context(self.SECTION_REF_CONTEXT)
return RoseDirective.run(self)
class RoseXRefRole(XRefRole):
"""Handle references to Rose objects.
This should be minimal."""
def process_link(self, env, refnode, has_explicit_title, title, target):
# copy ref_context to the refnode so that we can access it in
# resolve_xref. Note that walking through the node tree to extract
# ref_context items appears only to work in the HTML buider.
refnode['ref_context'] = dict(env.ref_context)
return title, target
class RoseDomain(Domain):
"""Sphinx extension to add the ability to document Rose objects.
Example:
Click :guilabel:`source` to view source code.
.. code-block:: rst
.. rose:app: foo
An app called ``foo``.
.. rose:conf: bar
A setting called ``bar`` for the app ``foo``.
.. rose:conf: baz
A config section called ``baz`` for the app ``foo``.
.. rose:conf: pub
A config setting called ``[baz]pub`` for the app ``foo``.
"""
name = 'rose'
"""Prefix for Rose domain (used by sphinx)."""
label = 'Rose'
"""Display label for the Rose domain (used by sphinx)."""
object_types = {
'app': ObjType('app', 'app', 'obj'),
'file': ObjType('file', 'file', 'obj'),
'conf': ObjType('conf', 'conf', 'obj'),
}
"""List of object types, this should mirror ``directives``."""
directives = {
'app': RoseAppDirective,
'file': RoseFileDirective,
'conf': RoseConfigDirective,
}
"""List of domains associated with prefixes (e.g. ``app`` becomes the
``rose:app`` domain."""
roles = {
'app': RoseXRefRole(),
'file': RoseXRefRole(),
'conf': RoseXRefRole(),
}
"""Sphinx text roles associated with the domain. Text roles are required
for referencing objects. There should be one role for each item in
``object_types``"""
initial_data = {'objects': {}} # path: (docname, synopsis)
"""This sets ``self.data`` on initialisation."""
def clear_doc(self, docname):
"""Removes documented items from the Rose domain.
Not sure why, but apparently necessary.
"""
for fullname, (pkg_docname, _l) in list(self.data['objects'].items()):
if pkg_docname == docname:
del self.data['objects'][fullname]
def get_objects(self):
"""Iterates through documented items in the Rose domain.
This method is used to generate the Rose component of the inventory
file which in turn is used to cross-reference objects between sphinx
projects (via inter-sphinx).
See ``sphinx.util.inventory.InventoryFile.dump``.
Note:
The Rose domain does things a little bit differently in this area
to the Python domain as all Rose objects are stored in a single
flat dictionary whereas Python objects are stored in a nested one
and are namespaced accordingly.
Yields:
tuple - (name, dispname, type, docname, anchor, priority)
- name - The Rose object reference minus the ``:rose:type:``
stuff.
- dispname - For searching / linking.
- type - The Rose object type i.e. ``file``, ``app``, ``conf``.
- docname - The path to the file where the object is documented
(without extension).
- anchor - URL fragment for locating object on the page.
- priority - Hardwired to 1.
"""
for obj_name, (doc_name, _) in list(self.data['objects'].items()):
# obj_name -> The full object reference to the rose object
# e.g. `:rose:file:rose-app.conf`.
# doc_name -> The path to the document containing the rose object.
try:
# Split the obj_name into it's constituent components:
# 1. domain - i.e. `rose`.
# 2. type - i.e. `file`, `app`, `conf`.
# 3. ref_name - The remainder of the reference.
_, type_, ref_name = obj_name.split(':', 2)
except ValueError:
LOGGER.warning(
'Could not parse object reference for "%s"' % ref_name
)
continue
yield ref_name, ref_name, type_, doc_name, obj_name, 1
@staticmethod
def validate_external_xref(env, typ, target, node, intersphinx_mapping):
"""Check that the cross-reference is valid else log a warning.
Args:
intersphinx_mapping (str): A key from the Sphinx configuration of
the same name.
Returns:
bool: True if valid.
"""
try:
# Get the inter-sphinx mapping.
cross_target = env.config.intersphinx_mapping[intersphinx_mapping][
0
]
except KeyError:
LOGGER.warning(
'Could not find inter-sphinx mapping for "%s"'
% intersphinx_mapping
)
return False
except AttributeError:
LOGGER.warning(
'inter-sphinx required for cross-project ' 'references.'
)
return False
try:
# Test that there is a rose object in that mapping.
env.intersphinx_cache[cross_target][2]['rose:%s' % typ][target]
except (IndexError, KeyError, ValueError):
LOGGER.warning(
'No Ref for "rose:%s:`%s:%s`"'
% (typ, intersphinx_mapping, target),
location=node,
)
return False
return True
def resolve_xref(
self, env, fromdocname, builder, typ, target, node, contnode
):
"""Associate a reference with a documented object.
The important parameters are:
typ (str): The object type - see ``RoseDomain.object_types``.
target (str): The rest of the reference as written in the rst.
This implementation simplifies things by storing objects under their
namespace which is the same syntax used to reference the objects i.e:
.. rose:app: Foo
Creates the entry ``self.data['objects']['rose:app:foo']``.
Which can be referenced in rst by:
.. code-block:: rst
:rose:app:`foo`
"""
# If target has a trailing argument ignore it.
target = OPT_ARG_REGEX.search(target).groups()[0]
# Handle inter-sphinx cross-references
match = CROSS_DOMAIN_REGEX.match(target)
if match:
# This is a cross-reference to a Rose object in another Sphinx
# project (via inter-sphinx).
intersphinx_mapping, target = match.groups()
self.validate_external_xref(
env, typ, target, node, intersphinx_mapping
)
# The reference itself is handled somewhere else.
return
# Determine the namespace of the object being referenced.
if typ in ['app', 'file']:
# Object is a root rose config - path is absolute.
namespace = 'rose:%s:%s' % (typ, target)
elif typ == 'obj':
# Object is an 'obj' e.g. an environment variable, 'obj's are not
# referenceable (yet).
return None
elif typ == 'conf':
relative_to_conf = False
if target.startswith('['):
# Target is relative to the context conf_file.
relative_to_conf = True
# Get the referenced namespace in tokenised form.
reference_namespace = tokenise_namespace(
'rose:%s:%s' % (typ, target)
)
if reference_namespace[0][0] in ['rose:app', 'rose:file']:
# Target is a root rose config - path is absolute.
namespace = 'rose:%s:%s' % (typ, target)
else:
# Target is not a root config - path is relative.
context_namespace = tokens_from_ref_context(
node['ref_context']
)
if not context_namespace:
LOGGER.warning(
'Relative reference requires local context '
+ '"%s".' % (target),
location=node,
)
return
if relative_to_conf:
# Target is relative to the context conf_file.
namespace_tokens = (
context_namespace[:1] + reference_namespace
)
else:
# Target is relative to the current namespace.
namespace_tokens = (
context_namespace[:-1] + reference_namespace
)
# Convert the tokenised namespace into a string namespace.
namespace = namespace_from_tokens(namespace_tokens)
# Lookup the object from the namespace.
try:
data = self.data['objects'][namespace]
except KeyError:
# No reference exists for "object_name".
LOGGER.warning('No Ref for "%s"' % namespace, location=node)
return None
# Create a link pointing at the object.
return make_refnode(
builder, fromdocname, data[0], namespace, contnode, namespace
)
[docs]
class RoseAutoDirective(Directive):
"""Directive for autodocumenting Rose configuration files.
Uses RST formatted comments in Rose configuration files using
:py:mod:`metomi.rose.config`.
Note the directive only documents config objects not the file itself.
Example:
.. code-block:: rst
.. rose:file: foo.conf
.. autoconfig:: path/to/foo.conf
"""
option_spec = {}
required_arguments = 1
domain = 'rose'
def run(self):
filename = self.arguments[0]
# Load rose configuration.
try:
conf = config.load(filename)
except config.ConfigSyntaxError:
LOGGER.error(
'Syntax error in Rose configuration file "%s".' % filename
)
raise
nodes = []
nodes.append(
addnodes.highlightlang(
lang='rose', force=False, linenothreshold=20
)
)
# Append file level comments if present.
if conf.comments:
contentnode = addnodes.desc_content()
contentnode.document = self.state.document
self.state.nested_parse(
StringList(conf.comments), self.content_offset, contentnode
)
nodes.append(contentnode)
# Append configurations.
section = None
node = block_quote()
for key, conf_node in sorted(conf.walk()):
if isinstance(conf_node.value, str):
# Configuration setting - "name=arg".
name = '%s=%s' % (key[-1], conf_node.value or '')
else:
# Configuration section - "name"
name = key[-1]
# Prepare directive object.
directive = RoseConfigDirective(
'rose:conf',
[name],
{},
StringList(conf_node.comments),
self.lineno,
self.content_offset,
self.block_text,
self.state,
self.state_machine,
)
if isinstance(conf_node.value, dict):
# Configuration section.
if section:
node.append(section.run()[1])
section = directive
elif key[0]:
# Sub-configuration.
section.register_subnode(directive)
else:
# Top-level configuration
node.append(directive.run()[1])
if section:
node.append(section.run()[1])
nodes.append(node)
nodes.append(
addnodes.highlightlang(
lang='bash', force=False, linenothreshold=20
)
)
return nodes
def setup(app):
app.add_domain(RoseDomain)
app.add_directive('autoconfig', RoseAutoDirective)