[Docs for engineering] Create a python script to update tagged docs with admonition

[stichbury]

Extends #3547

I'd like us to have something along the lines that I've created on this branch using sphinx-tags but without all the overhead of the actual tags in the toctree as we don't need that. Instead I'd like to have a simple way to mark up a docs page with these options:

• a warning "This doc may need revision" + Link to GitHub issue or
• a danger sign "We know there are problems in this doc" + Link to GitHub issue

See the prototype-docs-tagging branch for the mockup and the sphinx-tags repo and docs for details.

Using both tags at once to illustrate:

We do not need:

• page in toctree that lists all the tags used
• pages in the toctree for each of the tags (but to clarify, it would be helpful to be able to build a list of pages using each tag, just not publish them in the toctree alongside those docs)
• links in docs pages from the tag where it's used to the pages above

We do need:

• option for colours
• option for custom text in tag
• option for link to GitHub in tag

[astrojuanlu]

Is this essentially admonitions? Like

https://github.com/kedro-org/kedro/blob/de435f23a55a2407ea304ad764ebe8fa0a65c7d8/docs/source/deployment/index.md?plain=1#L39-L44

Rendered:

[stichbury]

It is but it isn't. We've used those in the absence of anything better right now.

(a) I don't want it to look like the content admonitions: this is a meta level about the docs rather than about Kedro usage. Also it makes it hard to find just the admonitions about docs content when they're formatted like everything else, which leads to the second point...

(b) I want a way to gather together all the docs warnings/danger tags so the team can easily list which pages are problematic. Hence the use of the tags extension (but ideally we don't display the page in the toctree -- I've excluded it in my prototype for a reason)

Does that make sense?

[astrojuanlu]

Proposed syntax:

---
doctags:
  warning: This page needs update. See [#2825](https://github.com/kedro-org/kedro/issues/2825) for details
---

# Title

Content...

(doctags name bikesheddable)

This uses YAML frontmatter to assign key-value page-wide metadata https://myst-parser.readthedocs.io/en/latest/configuration.html#frontmatter-local-configuration

How to check the metadata in code:

https://github.com/sphinx-doc/sphinx/blob/fa290049515c38e68edda7e8c17be69b8793bb84/sphinx/builders/html/init.py#L941-L942

As an inspiration, it's what the ablog extension uses to detect blog posts:

https://ablog.readthedocs.io/en/stable/manual/markdown.html

It uses a barely documented feature called "Sphinx transforms" https://github.com/sunpy/ablog/blob/de37cf013846ceccae0e9e478f4ed6e1bd2dd0d3/src/ablog/post.py#L183 (configured in https://github.com/sunpy/ablog/blob/de37cf013846ceccae0e9e478f4ed6e1bd2dd0d3/src/ablog/init.py#L150)

How to create a custom node: https://www.sphinx-doc.org/en/master/development/tutorials/todo.html#writing-the-extension

The styling would be done entirely on CSS.

[astrojuanlu]

OTOH, https://github.com/melissawm/sphinx-tags/ (the original extension @stichbury tried) is mostly there, save for https://github.com/melissawm/sphinx-tags/issues/97. So an alternative would be to fork it and tweak it to our needs.