initial implementation of sectioning (DO NOT MERGE)

[rscohn2]

Subject: option to add TOC entry for function, class, etc

Feature or Bugfix

• Feature

Purpose

• Partially addresses Create a ToC entry for every function, method, class, etc #6316. I like to organize my API in groups that are nested in sections. An entire group should be on a single (html) page and appear individually in the TOC. I looked at alternatives like exhale and breathe-apidoc and explain the issues in #index for doxygengroup breathe-doc/breathe#466

I am seeking comments on API and implementation and do not expect the PR to be merged in its current form.

Some things that are missing:

• method to apply it to groups of definitions without explicitly adding :section: to each
  My hope is to add the same option to doxygengroup in breathe and have it generate :section: for
  every entry. A config variable would also be useful.
• call the option :section: or :toc:?
• Section name is full signature. Need to make it match the index name
• Understanding of what should happen for nested objects
• probably more ...

I added a few sentences to the sphinx documentation to explain how it is used.

Thanks to @melvinvermeeren & @jakobandersen for their help so far.

[tk0miya]

Which is your goal to make a section or to put this function to ToC? I thought former one is not a goal of users. So it is better to implement latter way.

BTW, I feel a bit strange to add new options to object-description directives. The responsibility of them is to describe what the object is. So -1 for add option to here. How about adding a new config value instead?

[rscohn2]

My goal is to put the function in the TOC. I will look at doing it directly instead of creating the section.

I am working on a big doc with multiple parts so having a single global config would not work. There needs to be a way to turn on the option for a region of the doc, but not all.

Closing the pull request while I investigate some more