Allow admonitions without a title

[pradyunsg]

trafficstars

Is your feature request related to a problem? Please describe.

Allow authors to create an admonition that does not contain a title.

Describe the solution you'd like

Allow not having a title on in admonition.

.. admonition::

   Content

Describe alternatives you've considered

• Maintaining status quo, where users are continued/required to specify a title on their admonitions.
• Defining my own admonition-like directive, that allows omitting the title. This has been done, as part of themes within the Sphinx community already: https://jbms.github.io/sphinx-immaterial/admonitions.html#removing-the-title
• Supporting :class: notitle-important in the theme, which hides the title for all non-screen-reader users.
• Adding a :screen-reader-only-title: option to all admonition directives, which would indiciate to themes that they should hide the admonition title for all non-screen-reader users.

Additional context

I'm working on https://github.com/pradyunsg/lutra/, which is where I realised that this would be a useful UI element to provide to documentation authors. For example, one could use this to wrap blocks of content examples, to show "good" vs "bad" using colors.

Example from the sphinx-immaterial:

[jdknight]

This is enforced by docutils [1]; however, maybe it would be possible to patch it (if desired/possible).

Have you tried messaging the docutils mailing list to see if they are willing to drop the requirement of the argument?

[2bndy5]

In #10958 I similarly proposed a no-title option for the specific admonitions. I agree that the general admonition should be patched to accept 1 optional argument instead of 1 required argument. None of this should be a breaking change to users as the current implementation will still work.

[2bndy5]

@pradyunsg We have updated the sphinx-imaterial theme's use of admonitions to incorporate our own overrides using our new Custom Admonitions feature. So, the link in the OP no longer points to the intended info/demo.

You can still reference the older version of the theme's docs from our RTD project: https://sphinx-immaterial.readthedocs.io/en/v0.7.3/admonitions.html#removing-the-title