[Sphinx] [Automation] Make it possible to create hierarchical document structures

[felix91gr]

There's currently no way to write Guidelines where a section has hierarchical structure.

This is not an issue for very short cases, since such a structure is not needed there. But for more cases where, for example, the Rationale has multiple focus points, being able to use something akin to HTML headings would make the Guidelines more accessible for screen reader users, as well as more easily searchable by tools.

Here I give an example of this need. This is how it was phrased:

With a hierarchical structure, the rationale is parsed like a tree, which facilitates navigation and mimics the way one reads multi-part documents.

Intro
Reason 1
    Context and explanation for Reason 1
Reason 2
    Context and explanation for Reason 2

But with bold and other such formatting, the rationale is parsed like a homogeneous document:

Intro
Reason 1
Context and explanation for Reason 1
Reason 2
Context and explanation for Reason 2

I want a way to get the former kind of structure. Is there a way we could do that?

CC @x0rw since you're our expert on RST. Please let me know how I can help make this possible.

[x0rw]

Hey @felix91gr, following up on #166
CC @PLeVasseur

To create hierarchical structures the best way i can think of is through unordered lists, eg:

- **Intro**
- **Reason 1**
  - Context and explanation for Reason 1
- **Reason 2**
  - Context and explanation for Reason 2

This will render in sphinx into:

Heres a longer example:

- **Intro**  
  This section gives an overview.

- **Reason 1**  
  Context and explanation for Reason 1.

  - **Detail 1.1**  
    Extra info about detail 1.1.

    - **Sub-detail 1.1.1**  
      Even deeper explanation for 1.1.1.

  - **Detail 1.2**  
    Another branch of reasoning.

- **Reason 2**  
  Context and explanation for Reason 2.

  - **Detail 2.1**  
    Supporting evidence.

  - **Detail 2.2**  
    More elaboration with a note:

    > This could be important for implementation.

This will be renderd into:

If there is a need for more complex hierarchical structures let me know.

Hope this helps, and thanks for your patience with my late reply.

[felix91gr]

Hope this helps, and thanks for your patience with my late reply.

No worries. Again, I'm thankful that you had the time.

To create hierarchical structures the best way i can think of is through unordered lists, eg:

I was surprised to see that this actually puts the <li> ... </li> brackets in the right places. This is great! I'm using it to fix the issues we had with #156 and #174.

I have a nitpick with Markdown itself here, which is that I don't like semantic whitespace, but... oh well. It is what it is.

A bonus feature of this is that I can out-nest of the list item, as can be seen now in the last paragraph of #174. That's something I didn't have access to with just heading-based nesting.

[felix91gr]

CC @x0rw