Ability to repeat an admonition

[LecrisUT]

Let's consider that we have a similar admonition for warning, tldr, etc. that is repeated in multiple documents. It would be nice to have a simple way of just including the content from a centrally defined one, without using include directive

[SilverRainZ]

What's the problem with include?

[LecrisUT]

In this case, the indirectness. I would have to manage a separate file with some kind of tagging mechanism. And then there's the issue that name amd other indexing would not work because of its duplication

[electric-coder]

It would be nice to have a simple way of just including the content from a centrally defined one, without using include directive

No it would not be nice! Because it would require adding a superfluous functionality with no concrete gains.

And then there's the issue that name amd other indexing would not work because of its duplication

You don't give any examples but the index isn't supposed to have duplicates, if it had a duplicate how would you choose which one to cross-reference? You can always define an arbitrary location above an include directive if you need it.

[LecrisUT]

@electric-coder I have spun up a MWE to show how the name directive can be problematic: https://github.com/LecrisUT/sphinx-admonition-mwe

Notice that test-warning is generated only once, and where it points is arbitrary. If I run myst-inv I get the following:

name: Sphinx MWE
version: ''
base_url: http://localhost:8000
objects:
  std:
    label:
      genindex:
        loc: genindex.html
        text: Index
      modindex:
        loc: py-modindex.html
        text: Module Index
      py-modindex:
        loc: py-modindex.html
        text: Python Module Index
      search:
        loc: search.html
        text: Search Page
      test-warning:
        loc: other_page.html#test-warning
        text: null
    doc:
      index:
        loc: index.html
        text: Sphinx admonition MWE
      other_page:
        loc: other_page.html
        text: Another page
      referencing_page:
        loc: referencing_page.html
        text: Referencing page

Having only the content be included would minimize these unexpected effects.

[electric-coder]

@LecrisUT that's not a good MRE. If you're pasting a directive with the same name twice you're making an error. Sphinx is working correctly.

Besides, if you're including the whole admonition you can also include just the content and write the declarations with different names. Or you can write your own extension. What you're proposing is superfluous and following your logic the include directive should also then change its content's name for any other directive it might contain. Basically you're proposing that every directive be duplicated for a dubious convenience of questionable utility.

The kind of functionality you're proposing can be a 3rd party extension but it would only bloat Sphinx core with redundancy.

[picnixz]

It would be nice to have a simple way of just including the content from a centrally defined one, without using include directive

You can use substitutions. Put everything you want in your rst_prolog and then you'll just use .. warning:: |MY_WARNING_TEXT|.

I haven't tested it, but it should work. If it doesn't work, you can add handler for autodoc_process_docstring where you just replace all occurrences of whatever you consider a tag with the corresponding RST content (not the best solution since it's autodoc-based only).

For now I'll close the issue, but feel free to reopen if none of my solutions work.

[LecrisUT]

With regards to working, these solutions can technically work, but it is not a clean design for the user: having to tag the include sections, having to create a dedicated file/variable to use the substitution, etc. I'm just saying that having an interface like:

:::{warning}
: from: warning-about-version
:::

feels more natural to read and navigate

[picnixz]

I would suggest this feature to myst rather than to Sphinx itself. Or it should be something like we use for translation where you replace placeholders by the translation.

In the future we may support this but for now it's not planned.