Merge topic 'cmake-diagnostics-doc'

95f7f84609 Help: Fix CMD_INSTALL_ABSOLUTE_DESTINATION documentation
a882ec84ec cmDocumentation: Add diagnostics
97d13c3053 Help: Improve diagnostics documentation
3cccce8ca2 Help: Add developer documentation for new diagnostics
ffe4c2a8ff Help: Fix developer documentation

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Robert Maynard <robertjmaynard@gmail.com>
Merge-request: !11996

Utilities/Sphinx/cmake.py

@@ -234,6 +234,7 @@ class _cmake_index_entry:
 _cmake_index_objs = {
     'command':    _cmake_index_entry('command'),
     'cpack_gen':  _cmake_index_entry('cpack generator'),
+    'diagnostic': _cmake_index_entry('diagnostic'),
     'envvar':     _cmake_index_entry('envvar'),
     'generator':  _cmake_index_entry('generator'),
     'genex':      _cmake_index_entry('genex'),
@@ -523,6 +524,79 @@ class CMakeSignatureObject(CMakeObject):
         return super().run()
 
 
+class CMakeDiagnosticObject(CMakeObject):
+    object_type = 'diagnostic'
+    required_arguments = 0
+    optional_arguments = 0
+
+    DEFAULT_CHOICES = {'ignore', 'warn', 'error'}
+
+    def default_option(argument):
+        return directives.choice(
+            argument, CMakeDiagnosticObject.DEFAULT_CHOICES)
+
+    option_spec = {
+        'default': default_option,
+        'parent': directives.unchanged,
+    }
+
+    def __init__(self, *args, **kwargs):
+        self.targetname = None
+        super().__init__(*args, **kwargs)
+
+    def _preset_name(self) -> str:
+        sep = False
+        out = ''
+        for c in self.targetname[4:]:
+            if c == '_':
+                sep = True
+            elif sep:
+                out += c
+                sep = False
+            else:
+                out += c.lower()
+        return out
+
+    def _build_field(self, name: str, content: str | list[Node]) -> Node:
+        if type(content) is not list:
+            content = self.parse_text_to_nodes(content)
+
+        name_node = nodes.field_name(text=name)
+        body_node = nodes.field_body('', *content)
+        return nodes.field('', name_node, body_node)
+
+    def _build_cli(self) -> list[Node]:
+        cname = self.targetname[4:].lower().replace('_', '-')
+        ctext = f'-W[no-][error=]{cname}'
+        return self.parse_text_to_nodes(f':option:`{ctext} <cmake -W>`')
+
+    def _build_preset_refs(self) -> list[Node]:
+        p = self._preset_name()
+        w = f':preset:`warnings.{p} <configurePresets.warnings.{p}>`'
+        e = f':preset:`errors.{p} <configurePresets.errors.{p}>`'
+        return self.parse_text_to_nodes(f'{w}, {e}')
+
+    def run(self) -> list[Node]:
+        self.domain, self.objtype = self.name.split(':', 1)
+        doc = self.state.document
+        self.targetname = doc.next_node(nodes.title).astext()
+
+        default = self.options['default'].capitalize()
+        parent = self.options.get('parent')
+
+        headers = nodes.field_list()
+        headers += self._build_field('Command Line', self._build_cli())
+        headers += self._build_field('Presets', self._build_preset_refs())
+        headers += self._build_field('Default', default)
+
+        if parent:
+            parentRef = self.parse_text_to_nodes(f':diagnostic:`{parent}`')
+            headers += self._build_field('Parent', parentRef)
+
+        content = self.parse_content_to_nodes()
+        return [headers] + content
+
+
 class CMakeReferenceRole:
     # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'.
     _re = re.compile(r'^(.+?)(\s*)(?<!\x00)<(.*?)>$', re.DOTALL)
@@ -680,6 +754,7 @@ class CMakeDomain(Domain):
     object_types = {
         'command':    ObjType('command',    'command'),
         'cpack_gen':  ObjType('cpack_gen',  'cpack_gen'),
+        'diagnostic': ObjType('diagnostic', 'diagnostic'),
         'envvar':     ObjType('envvar',     'envvar'),
         'generator':  ObjType('generator',  'generator'),
         'genex':      ObjType('genex',      'genex'),
@@ -700,6 +775,7 @@ class CMakeDomain(Domain):
     directives = {
         'command':    CMakeObject,
         'envvar':     CMakeObject,
+        'diagnostic': CMakeDiagnosticObject,
         'genex':      CMakeGenexObject,
         'signature':  CMakeSignatureObject,
         'variable':   CMakeObject,
@@ -710,6 +786,7 @@ class CMakeDomain(Domain):
         'cref':       CMakeCRefRole(),
         'command':    CMakeXRefRole(fix_parens=True, lowercase=True),
         'cpack_gen':  CMakeXRefRole(),
+        'diagnostic': CMakeXRefRole(),
         'envvar':     CMakeXRefRole(),
         'generator':  CMakeXRefRole(),
         'genex':      CMakeXRefRole(),