Add `include_rubrics_in_toc` object description option

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system

https://jbms.github.io/sphinx-immaterial/

Other

196 stars 29 forks source link

Add `include_rubrics_in_toc` object description option #136

Closed mhostetter closed 2 years ago

mhostetter commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

mhostetter commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

Thanks