Ability to link to deeper parts of the documentation

[david-perez]

This is a feature request.

When referencing parts of the spec (with colleagues, or in smithy-rs), I'd often like to link to more specific parts of the documentation.

For example, I can link to section 11.5, the httpPayload trait, but that section has a bunch of provisions that I can't refer to when implementing a test in code: for example, I can't link to the "Protocol-specific document payloads" section.

It'd be very nice if we could link granularly to these provisions.

I don't know how to change the documentation so that things like "Value type", "Conflicts with" are linkable, but it seems like if you changed these rubric directives for regular subsections (-) or subsubsections (^), Sphinx would make them linkable in the HTML and appear in the TOC, if rendered with sufficient depth?

[mtdowling]

We tend to use rubric for things that we aren't sure are permanent fixtures in the documentation specifically so people don't link to them and we end up breaking their links. Adding links to are too granular makes it harder for us to maintain and evolve the documentation over time. Things like linking to "Value type" and "Conflicts wtih" are too granular I think, and we've even talked about changing the presentation of traits. Adding a link for these specific httpPayload sections is something we can do though.

[david-perez]

I think breaking links is perfectly fine. The user will still land on the correct page, it's just that the anchor will not work. It's still a better situation over the current one.

[mtdowling]

Replacing rubrics with title links sounds fine to me 👍