Custom roles and domains in Sphinx with one line

I was working on the roles and structure section of the 2i2c Team Compass and found a nifty feature in Sphinx that I hadn’t known before.

You can currently add labels to any section with the following MyST Markdown structure:

(mylabel)=
## My header

And now I [reference it](mylabel).

However, there are no semantics attached to this label. Instead I’d like to be able to specify what kind of a label this is. In my case, it’s because I wanted to define a group of labels attached to our organization’s roles.

Fortunately this is pretty easy to do! Just not well-documented.

Here’s how to define a custom role and reference it in Sphinx:

1. Register your new role group. In your conf.py configuration, use app.add_crossref_type like so:

   def setup(app):
       app.add_crossref_type("labelmygroup", "mygrp")

   The first argument labelmygroup is the name of a directive that you’ll now be able to use to attach a section of your documentation to this role group.

   The second argument mygrp is the name of a role that you can now use to refer to an group that was labeled with labelmygroup.

2. Add a group label to a section with a directive. You can do this like so:

   ```{labelmygroup} Some name
   ```
   ## Group description

3. Reference the label with a role. You can now reference the Some name group with a role, like so: Here is {mygrp}`Some name`.

This is a nice way to have semantic references throughout your docs (like {role}`Executive Director`) rather than generic ones.

See the Sphinx Documentation on this for more details.