Add custom Sphinx roles for editor UI

[tetrapod00]

This PR is a proof of concept, and is subject to change. It only implements the custom roles and a short example usage section. I have a separate branch for actual usage changes, with several hundred already changed. Decisions of which roles to add are being driven by actual usage.

What this is

This PR adds custom Sphinx roles, like :btn:, :menu:, and :ui:, for various editor UI elements. It renders most of them with bold text and a light blue-gray background.

It looks like this:

Or this:

Currently implemented are:

• :btn: A button, toggle, or most other clickable UI elements. If the reader is meant to click on it, and it's not a menu, use this.
• :menu: A series of menus to click through, or a single menu to click on. When listing a series of menus, separate them with >.
• :uiproperty: A property in the inspector. Note that you can also link to a property, or use code style to refer to a property when used in code rather than the inspector. It's called "uiproperty" and not "property" for a reason, since inspector properties are treated differently than properties accessed through code. "property" or "prop" should be reserved for future use for the other case. This name is definitely too long, it will be changed.
• :ui A catch-all role for any editor UI elements. Use this if you would have otherwise just used bold style. It can be changed later, if necessary.
• :field: An input field in the editor; anything that you type into. Excludes properties, though.
• :path: A UI navigation path in the editor. Use :uisection: instead for nested sections in the inspector. Use :uiproperty: instead for inspector properties that include a section like Process > Mode. Use :projsection: for sections in the project settings. Probably will be merged with menu, but I'm keeping both around to see if there is some nuance to their usage to preserve.
• :wndw: An editor window, popup dialog, or modal. Anything that can be separately dragged and has a title.
• :uisection: A section in the inspector. Likely will be renamed to be shorter.
• :projsection: A section in the project settings. Likely will be renamed to be shorter.
• :tab: A tab.
• :dock: A dock.
• :panel: A panel.

As you can see, some are very specific, and some are probably redundant. I'm tagging very specifically first, then I'll come back and merge them together based on actual usage.

Why

This solves two problems, style inconsistency and maintenance.

Style inconsistency: Style for UI elements in the editor is inconsistent. For buttons, we currently use bold, italics, code, or "quotes". We've mostly standardized on bold, but there are a lot of existing usages that are inconsistent.

Maintenance: Using semantically meaningful roles for each separate kind of editor UI allows us to change the style of each one independently, without breaking translations, just by changing the CSS. It also makes searching for all instances of one kind of editor UI much easier, since the tag can be searched.

Technical details

The custom roles are defined inline in rst_prolog. I experimented with more complex custom roles as a Sphinx extension, but they are not needed. All this can be accomplished in Sphinx userspace with CSS and some simple definitions:

.. role:: btn
   :class: uibutton uistyle

However, in the future we can change these roles to have more complex behavior, without changing the RST content files. Since all the usages will already be tagged, we can switch out the implementation of the role seamlessly.

Downsides

• Source files are less readable.
• Source files are a bit harder to type.
• Markdown previews become less useful. Some of the new roles simply render as bold, but since they no longer use **, previews don't know that.
• Contributors have to know about the specific tags, rather than just using bold as they see fit. I think this can be mitigated by using btn, menu, and ui as general-purpose tags. If the tag needs to be made more specific, it can be done in review by a contributors who are more familiar. Or we can limit the overall number of tags.
• Huge translation churn for the initial set of changes.

Q & A

Why not just use :guilabel:?

Sphinx's guilabel and menuselection roles are the inspiration for this PR. I tried them in #10238. They look like this:

For one reason, the name is too long, very annoying to type. For another, it's not granular enough in my opinion. It solves the style inconsistency problem, but does not solve the maintenance problem, since many things would be tagged together under one label.

Why so many specific roles?

All existing usages must be changed from bold, italics, etc to use a role. It's easier to tag them very specifically on the first pass, then replace specific roles with generic ones. We might decide to only use a few roles (I would pick :ui:. :btn:, and :menu:, and one for inspector properties).

Why :btn: and not :button:, :wndw: not :window:, etc?

I wasn't sure about this myself but after replacing a lot of usages, the extra letters do add up! I think 3-5 is the sweet spot.

Why not enforce a style guideline by hand?

We currently do this, and the manual is currently not consistent. Why not let the computer handle the formatting?

How many existing usages to change?

Just for existing bold usage, I found hundreds of instances to change. But after I started actually looking in files, there are lots more than this. Probably on the order of 2000+ usages to change. I think I've changed several hundred in my other branch already.

• 48 instances of **Something** button
• 9 instances of **Something** window
• 33 instances of **Something** menu
• 18 instances of **Something** setting
• 7 instances of **Something** dropdown
• 7 instances of **Something** field
• 268 instances of **UI > Navigation > Path**
• 95 instances of **Inspector Property**
• 14 instances of click on **Something**
• 52 instances of click **Something**
• 35 instances of select **Something**
• 24 instances of enable **Something**
• 46 instances of **Something** tab

Won't this cause a lot of translation churn?

Yep! That's why I want to do it once, using fairly granular tagging, and then in the future we can change style with CSS instead of editing the RST content directly.

Future plans

At some point I'd like to take a shot at implementing a :property: or :method: role that autolinks to the class reference (and ideally is smart enough to link on the first usage in a page, then use code style. See #8890. This PR is a first step towards that.