Introduce the tmt sphinx domain

[LecrisUT]

This sphinx domain has a few major components:

• Directives to define the tmt objects we document
• Index of all tmt objects we have documented
• Autodoc directives that take in the contents of the docsting etc. and fill in the contents of the tmt objects
• Resolver for cross-reference roles

Depends on: #4286

[happz]

Looks OK to me, but I would appreciate more documentation. Even a rudimentary, basic one, e.g. comments explaining purpose of various classes and most important methods. I presume most of the form is needed to integrate with Sphinx, autodoc API and other component, but that's just guessing. For example, I can't find what is using base.py, base.TmtAutodocDirective, is that automatic somehow? Feels like an opaque piece of code.

[LecrisUT]

Looks OK to me, but I would appreciate more documentation. Even a rudimentary, basic one, e.g. comments explaining purpose of various classes and most important methods. I presume most of the form is needed to integrate with Sphinx, autodoc API and other component, but that's just guessing. For example, I can't find what is using base.py, base.TmtAutodocDirective, is that automatic somehow? Feels like an opaque piece of code.

Done, see de10c1c.

[tcornell-bus]

Just for my understanding, this code is not used yet, right? This is just to lay the foundation? Cursor found a couple small things.

[LecrisUT]

Just for my understanding, this code is not used yet, right?

Yes, example usage is in #4288 specifically 56bd1c8 on how they are consumed.

[skycastlelily]

LGTM, after Therese comments are addressed.You might want to consider:)
● 4. Add detailed comments to the RST indentation logic:

● Update(docs/ext/tmt_domain/autodoc.py)
  ⎿  Updated docs/ext/tmt_domain/autodoc.py with 8 additions and 3 removals                
        96        def _indent_str(self, orig: str) -> str:
        97            """
        98            Prepend all the necessary indent and possibly the list symbol.
        99 +          
       100 +          This handles the complex RST indentation rules where list items need
       101 +          special formatting with bullet symbols.
       102            """
       103            if self.needs_list_symbol:
       104 -              # Indent the line and add the list symbol
       104 +              # RST list item formatting: "* " takes 2 chars, so we indent
       105 +              # (current_indent - 2) spaces, then add "* " + content
       106 +              # Example: if indent=5, we get "   * content" (3 + 2 = 5 total)
       107                self.needs_list_symbol = False
       108                return " " * (self.indent - 2) + "* " + orig
       109            if not orig.strip():
       110 -              # No need to indent if the line is empty
       110 +              # Empty lines don't need indentation in RST (would create issues)
       111                return ""
       112 -          # Indented line
       112 +          # Regular content: indent by current level (directive content, etc.)
       113            return " " * self.indent + orig
       114    
       115        @overload

● 5. Add comments to the directive context manager explaining RST structure

● Update(docs/ext/tmt_domain/autodoc.py)
  ⎿  Updated docs/ext/tmt_domain/autodoc.py with 12 additions and 3 removals                          
       196    
       197            # TODO: multiple signature is not supported
       198            # TODO: add some meaningful source like using inspect to get the caller's source
       199 -          # Add the directive header
       199 +          
       200 +          # Create RST directive header: ".. directive_name:: args"
       201            self.append(
       202                f".. {name}:: {', '.join(directive_args)}".rstrip(),
       203                source=source,
       204                offset=get_offset(),
       205            )
       206 +          
       207 +          # Increase indent for directive content (RST requires exactly 3 spaces)
       208            self.indent += RST_DIRECTIVE_INDENT
       209 +          
       210 +          # Add directive options (":option: value" format, also indented)
       211            for key, value in directive_kwargs.items():
       212                self.append(
       213                    f":{key}: {value or ''}".rstrip(),
       214                    source=source,
       215                    offset=get_offset(),
       216                )
       217 +          
       218 +          # Blank line required between directive header/options and content
       219            self.append(
       220                "",
       221                source=source,
       222                offset=get_offset(),
       223            )
       224 -          # Start adding other contents
       224 +          
       225 +          # Yield control to add directive content (will be auto-indented)
       226            yield self
       227 -          # exit the directive
       227 +          
       228 +          # Close directive with blank line and restore indentation
       229            self.append(
       230                "",
       231                source=source,

● Update(docs/ext/tmt_domain/autodoc.py)
  ⎿  Updated docs/ext/tmt_domain/autodoc.py with 7 additions and 1 removal               
       255                    return next(offset_count)
       256                return 0
       257    
       258 +          # Prepare for first list item (will add "* " when content is added)
       259            self.needs_list_symbol = True
       260            self.list_layer += 1
       261 +          
       262 +          # Increase indent by LIST_INDENT (2) for list content alignment
       263 +          # This accounts for the "* " that will be added to first item
       264            self.indent += LIST_INDENT
       265 +          
       266            yield self
       267 -          # exit the directive
       267 +          
       268 +          # Close list with blank line and restore previous indent level
       269            self.append("", source=source, offset=get_offset())
       270            self.indent -= LIST_INDENT
       271            self.list_layer -= 1

● Update(docs/ext/tmt_domain/autodoc.py)
  ⎿  Updated docs/ext/tmt_domain/autodoc.py with 4 additions                              
       277            Start adding the contents of a new item.
       278    
       279            Must be called within a :py:meth:`list` context.
       280 +          
       281 +          This sets a flag so the next content added will get the "* " prefix
       282 +          for proper RST list formatting.
       283            """
       284            if not self.list_layer:
       285                raise SyntaxError("new_item was used outside of a list context")
       286 +          # Mark that next content should get "* " list bullet prefix

[LecrisUT]

LGTM, after Therese comments are addressed.You might want to consider:) ● 4. Add detailed comments to the RST indentation logic:

I have a yes-and-no relation to the docstring suggestions.

This handles the complex RST indentation rules where list items

Not true, it is used in both with and without list items. The mixing of the ident and handle list symbol is not ideal but I haven't spent much time thinking on how I could separate it.

RST list item formatting: "* " takes 2 chars, so we indent

It is unnecessarily verbose IMO. Tried to keep the briefness of the previous comment and explain better the self.indent - 2 in there.

Empty lines don't need indentation in RST (would create issues)

Not really, they are completely ignored. In some of these cases I don't see how the comments are improved, and I want to be as minimally verbose in those as possible. If you do find some that I have missed which is indeed confusing, do raise it again.

Create RST directive header: ".. directive_name:: args"

Sure, makes sense, but I rather have that in the docstring. The code comment does not need to replicate the same contents, just to tag what is happening where. Did the same for the other 2 functions.

[psss]

While I don't understand all the sphinx implementation details, the overall structure looks good and works as expected. Checked with #4288 and the speedup is significant, nice! Ran into three typos.

[happz]

Documentation-only, merging.