Implement TOC inclusion in Directive class

[MK Latter]

I'm trying to get a Directive class (or the nodes it creates/handles) picked up by the TocTreeCollector as described here:

https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.directives.ObjectDescription._toc_entry_name

To that end:

class LeafDirective (ObjectDescription):

    def handle_signature(self, sig, signode):
        signode.replace_self(self.nodeFromSig(sig))
# Get fully qualified name, which is not in the sig but part of the domain state.
        cc = self.env.get_domain('cogsphinx').getCurrentContext()
        signode['fullname'] = f'{cc}::{sig}'
        signode += addnodes.desc_name(signode['fullname'], signode['fullname'])
        return sig

    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
        return tuple(sig_node['fullname'].split('::'))

    def _toc_entry_name(self, sig_node: desc_signature) -> str:
        return '.'.join(sig_node['_toc_parts'])

The _toc_parts tuple does show up properly in _toc_entry_name(). This is
derived from PyObject/PyFunction, since the directive is being used as a drop-in
replacement for the latter, which I have been (mis-)using for a while in non-python
projects because it works for the purpose and gets picked up in the TOC, but the
new directive still does not and I am now stumped.

The nodes created by the directive do have anchors and work properly with a custom
sphinx.domains.Index derived class.

Anyone here have any insight? Would have been great if the API simply had a
decisive "includeInToc()" or something...           

Thanks -- MK

[MK Latter]

The issue is that I call .replaceNode() with a node type that isn't desc_signature, so it fails some of the filtering implemented by TreeTocCollector.

That's not in the docs so I'll post a more complete solution here and maybe on S.0. soon(-ish).