Fix navigation for the docs

[purva-thakre]

Previously discussed here: https://github.com/unitaryfund/mitiq/issues/2278#issuecomment-2077751053

After moving to PyData theme for the docs, some of the left and right navigation sidebars appear blank.

Left Sidebar: 2nd Readme	Right Sidebar: User's Guide

To fix this issue, we will have to change the default options allowed by the theme in conf.py https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#overview-of-theme-layout https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#primary-sidebar-left https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#secondary-sidebar-right

I vote for keeping either the left or right sidebars; not both.

[jordandsullivan]

@purva-thakre Checking my understanding, it looks like on a normal page of the docs (i.e. not a top-level directory), the primary and secondary sidebars have different information: the high level section navigation and the page-level navigation, respectively:

While I agree this may be a bit busy for some, I think it's still useful to have both in this circumstance.

I vote for keeping either the left or right sidebars; not both.

Do you mean to keep only one sidebar across all of the docs or just on the specific pages you referenced above?

(Left Sidebar: 2nd Readme Right Sidebar: User's Guide)

[purva-thakre]

Do you mean to keep only one sidebar across all of the docs or just on the specific pages you referenced above?

For the pages that have blank sidebars, I think we should get rid of the blank ones if we can't manage to populate the blank area with information. But for those that have information in both sidebars, it's fine to keep them.

The last time I looked at this, I remember thinking we might have to mess around with the navigation depth for the blank sidebars. I haven't tried making these changes yet because the docs build takes forever.

[jordandsullivan]

@purva-thakre I don't see the original issue popping up on the linked pages. Do you?

[purva-thakre]

@jordandsullivan I think we discussed keeping this open during a community call due to issues with the API-doc.

The current version does not give you additional navigation options for all the top-level sections.

For example, if I click on Error-mitigation techniques in the right sidebar, we should be able to see all the available techniques in the form of a list. In v0.34.0, we can see this list when I click on the top level heading.

If you want, we could schedule pair-working sessions to understand why the top-level heading is not uncollapsing when we click on it in the right sidebar.

One option I can think of is using the left sidebar to list the sections under each top-level heading.

[purva-thakre]

Discussed with Alessandro and Jordan to disable the primary sidebar for the API-doc page.

We also tried messing with the navigation depth and levels. Did not work.

There's a possibility of a bug in the pydata-sphinx theme. A section in the secondary sidebar collapses when we click on the next section. The section does not collapse when we start to scroll through that particular section.

There was a major jump in the version number for the docs theme in v.34 of Mitiq where the API-doc sections were collapsing as expected.

https://github.com/unitaryfund/mitiq/compare/v0.34.0...v0.35.0

[cosenal]

I created a new issue for this on the theme repository: https://github.com/pydata/pydata-sphinx-theme/issues/1889