Add include_rubrics_in_toc object description option

[mhostetter]

Fixes #126. I believe I correctly implemented this feature. Please let me know your thoughts. I tested this locally on my project and on a standalone foo project.

The option is disabled by default. When enabled, all rubrics (that haven't already been converted to fields or admonitions by Napoleon) are added to the TOC. Here's an example in this foo module. foo-example.zip

[mhostetter]

The only slightly non-ideal thing I noticed was that rubrics from the class definition (not the __init__() signature) are included in the class TOC on the left-hand side.

@jbms have any thoughts on how that might be avoided?

I noticed that when you click on the class FLFSR on the left side, the "Notes", "References", and "Examples" TOC entries are not shown on the left. (which I prefer)

But when you select an individual method / property, then the "Notes", "References", and "Examples" appear on the left. (which I don't prefer)

[jbms]

No need to assign to target, instead should return as in the term case before since rubrics cannot contain children (because they are just headings, not sections). If you want them to be able to have chosen that would require more work.

[jbms]

The only slightly non-ideal thing I noticed was that rubrics from the class definition (not the __init__() signature) are included in the class TOC on the left-hand side.

@jbms have any thoughts on how that might be avoided?

I agree that this is not good. Does this issue occur with all sections, or just rubrics? If it occurs with all sections, the fix will be in nav_adapt.py

[mhostetter]

I agree that this is not good. Does this issue occur with all sections, or just rubrics? If it occurs with all sections, the fix will be in nav_adapt.py

By "all sections" do you mean the fields you convert into TOC headings, like "Parameters" and "Returns"? If so, yes. (I'm not sure how else to add section headings in a docstring.)

I just added "Parameters" and "Returns" into the class docstring and they manifest the same way the rubric TOC entries do.

[jbms]

Looks like nav_adapt.py needs to be fixed to exclude from the global toc section headings that don't themselves contain other pages as descendants.

[jbms]

Thanks, this looks perfect. The issue with the global toc is unrelated so it could be fixed separately I suppose.

[mhostetter]

@jbms thanks. I'm looking through the nav_adapt.py code and trying to figure it out. If I get too stuck, I may ask for help.

[mhostetter]

Ok... so... there's a lot going on in nav_adapt.py. Perhaps handing the global TOC should be a standalone issue. I'll open a new issue to track that. I'm ready to merge this PR whenever you all are ready. Thanks.

[jbms]

Thanks