Fix several issues with nav_adapt and add unit tests

[jbms]

Fixes #137. Fixes #138.

Also fixes support for only directives that affect sections.

[2bndy5]

I can confirm this fixes #138 and allows .. only:: (tested w/ html as arg) applied to .. toctree::.

@mhostetter can you confirm #137 is satisfied? I tested it with our autodoc example, but not with the apigen example.

@jbms I'm noticing the first entry in the global toc is missing for sub root pages. For example "General API customization" page isn't listed in the global toc but I can get to it by clicking "Formatting signatures" and hitting the "Previous" button at the bottom. I first noticed this when the demo_api page wasn't listed in the examples pages.

[mhostetter]

I'm noticing the first entry in the global toc is missing for sub root pages.

I noticed this too.

@mhostetter can you confirm https://github.com/jbms/sphinx-immaterial/issues/137 is satisfied? I tested it with our autodoc example, but not with the apigen example.

With include_rubrics_in_toc=True, I'm noticing that all the rubrics that were added to the TOC are now removed from both the left- and right-side TOCs (which is equivalent behavior to include_rubrics_in_toc=False).

Class example


Function example


[2bndy5]

when I added

.. rubric:: A rubric

to the autodoc'd class' docstr, and set

object_description_options = [
    ("py:.*", dict(include_rubrics_in_toc=True)),
]

The rubric showed in the local toc: I'm not sure if that's what was requested.

[mhostetter]

I'm not sure if that's what was requested.

That is the desired behavior. Not sure why I'm seeing something different. Perhaps it's the difference between autodoc and python-apigen. I'll have to do more testing.

[jbms]

Thanks for the testing. The issue with include_rubrics_in_toc was just that I had accidentally based my branch on an older commit before include_rubrics_in_toc was merged in. I have now rebased it.

Additionally, I have fixed the issue whereby the first child of a toctree with a :caption: was hidden.

Separately, I refactored the python domain fixes to split them into separate files, as was done previously for C++. As part of that refactor, I ensured that all monkey patching happens at module init time rather than during the setup function, to avoid issues if setup is called more than once (e.g. during unit tests where we build more than once per process).

[jbms]

I can confirm this fixes #138 and allows .. only:: (tested w/ html as arg) applied to .. toctree::.

To be clear, while it will build with only applied to a toctree, due to the linked Sphinx bug the only directive has no effect on the global toc --- the toctree is always included in the global toc regardless of the condition.

[mhostetter]

Thanks for the testing. The issue with include_rubrics_in_toc was just that I had accidentally based my branch on an older commit before include_rubrics_in_toc was merged in. I have now rebased it.

Thanks. It does appear that the rubrics are working as intended. See below that the "Examples" rubric is suppressed from the global TOC, which was the goal of #137. 👍

I did notice, though, that with python-apigen object pages now seem to have an extra heading. See below that the galois.BCH.generator_poly page with the yellow "P" marker appears as the first heading in the local TOC and generator_poly without the yellow "P" is added to the global TOC. The same is true for the extra heading in the galois.BCH page.

With `main`


With 488e35f


[jbms]

I did notice, though, that with python-apigen object pages now seem to have an extra heading. See below that the galois.BCH.generator_poly page with the yellow "P" marker appears as the first heading in the local TOC and generator_poly without the yellow "P" is added to the global TOC. The same is true for the extra heading in the galois.BCH page.

This was due to a bug in my refactoring of the Python domain monkey patches, which broke nonodeid (used by Python apigen). That is now fixed and I added a unit test.

[mhostetter]

This was due to a bug in my refactoring of the Python domain monkey patches, which broke nonodeid (used by Python apigen). That is now fixed and I added a unit test.

Awesome, thanks. I can confirm this works for me now. 👍

Separately, I refactored the python domain fixes to split them into separate files, as was done previously for C++.

I like the refactoring -- makes the code easier to follow.

[jbms]

Thanks for the review!

[2bndy5]

Think I'll push v0.8.1

[jbms]

Think I'll push v0.8.1

Sounds good