Create a Heading in a Directive

Is your feature request related to a problem? Please describe. I'm trying to write a directive that creates a heading and a toctree. But while I can create docutils.nodes.sections, sections that come from rst headings have different attributes. This becomes a problem because a transform in another extension is expecting all sections to have a nonempty "ids" attribute. It looks like the doctree contains "id1", "id2", etc for sections that come from rst headings.

Describe the solution you'd like I would like to be able call a directive that produces the docutils.nodes created when an RST heading is parsed.

Describe alternatives you've considered I can continue to go hunting for missing attributes and issues when errors appear, but I'm not sure if the problem is the different attributes that I need to set, or if those attributes are meant to be set by a transform, and it's being missed because my section is illegal without a implicit hyperlink reference. The docutils section description says that:

Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target (the "reference name") is the same as that of the section title.

(I've tried adding one, but (a) docutils leaves these nodes undocumented, and (b) I'm getting a system_message node in my result because something's going wrong.

Additional context If the problem is that my doctree is illegal, but sphinx is allowing my document to build, and I'm only discovering the illegal doctree because another extension relies on it being correct, sphinx should be the one raising the exception (or at least a warning) about the bad sections. (I am operating in -W mode, so warnings should be exceptions)

Same problem with links... I can't seem to generate the nodes for an external link without causing an error

While this description is pretty good (and dare I say we've all run into this) it's missing a minimal reproducer that shows the reST and the generated HTML with the difference in generated id clearly.

sections that come from rst headings have different attributes.

What do you mean by attributes here? Is it HTML attributes in the generated output or internal Python attributes of the Sphinx objects?

This becomes a problem because a transform in another extension is expecting all sections to have a nonempty "ids" attribute.

Here it gets even more complicated because, for example, each Sphinx theme might do different things in its generated output, so just an abstract description doesn't seem enough to me. (And that's not to mention what the many 3rd party extension might be doing independently.)

I would like to be able call a directive that produces the docutils.nodes created when an RST heading is parsed.

Here I'm not sure if this is an advanced usage question about the Sphinx API or if it's a feature request?

(I've tried adding one, but (a) docutils leaves these nodes undocumented, and (b) I'm getting a system_message node in my result because something's going wrong.

Again, no MRE and docutils is in the process of being migrated to get extra support... Without additional context we're guessing (or left to try and rewrite the code you're abstractly describing).

I can't seem to generate the nodes for an external link without causing an error

If you look carefully at the Stack Overflow Q&A for Sphinx and docutils you might notice that none of what you're describing is trivial (it's a functionality question that asks several API usage questions at once), and it might never have been asked or answered there. (Historically this is also because neither docutils nor Sphinx self-documented their APIs in full which caused regular devs to loose unreasonable amounts of time to solve these problems reverse-engineering the API from runtime behavior.)

The comment I'll add is that we need an MRE, and I'd have instant closed this thread at SO for lacking the MRE.

But I'll add a further dual comment, sections are reST structural elements and the question is about nesting them in depth with reST body elements, suffices to say this is already advanced usage and the question doesn't make itself clear by showing the specific circumstance where this behavior is aimed to be achieved.

The docutils section description says that:

Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target (the "reference name") is the same as that of the section title.

There are intricate HTML/JS/browser needs that might not be evident and may have changed over time to use the id as an anchor, the main reason is that when clicking an anchor the id is needed for the browser to automatically scroll to the anchor. But that behavior seeming trivial doesn't always hold depending on depth of nesting and the type/style of nested elements.

Describe the solution you'd like I would like to be able call a directive that produces the docutils.nodes created when an RST heading is parsed.

A "directive" in the reST sense would be:

heading
---------

.. directive: argument
   :option:
   body

So you want a "directive" that would give you during the processing of heading a docutils.nodes? You see why this formulation isn't self-explanatory?

sphinx-doc / sphinx

Create a Heading in a Directive #13109