It is very hard to find the design / example list now

[mithro]

The only place the designs and examples are listed is on the page @ https://f4pga-examples.readthedocs.io/en/latest/building-examples.html and they no longer appear in the left side bar.

[mithro]

@umarcor - This seems to be a regression / step backwards for usability.....

[mithro]

It was almost impossible for me to find the demos which run on the Zynq to answer the question at https://github.com/chipsalliance/f4pga-examples/issues/26

[mithro]

@kgugala - PTAL - I think the listing / menu thing is affecting many users of the theme.

[mithro]

BTW - This is what the example page looks like to me, I can't see any examples at first glance (have to scroll down);

[kgugala]

yeah, @umarcor is working on this (experimenting with a few different desings to figure out which will be most readable)

[umarcor]

I pushed eight tests to https://github.com/antmicro/f4pga-examples/blob/gh-pages. See https://github.com/antmicro/f4pga-examples/blob/gh-pages/theme_tests.md.

• A: .../testA/#: left sidebar depth is 1, items are linkable regardless of having children.
  • .../testA/building-examples.html: right sidebar depth seems to be 2.
• B: .../testB/#: same a A; since the left sidebar depth is 1, option globaltoc_collapse seems not to be relevant.
  • .../testB/building-examples.html: same as A.
• C: .../testC/index.html#: left sidebar depth is -1, but the depth is not to be relevant at the top-level.
  • .../testC/building-examples.html: the right sidebar seems to be the same as A; however, in the left sidebar the section is collapsible. As a result, the section cannot be accessed from itself or from any of the children through the left sidebar. At the same time, none of the children which do have children can be accessed from the left sidebar.
• D: .../testD/#: same as C, but the top-level items are also collapsible. As a result, none of the sections with children can be accessed through the left sidebar (only the right sidebar or tocs in the body allow linking).
  • .../testD/building-examples.html: same as C.
• E: .../testE/#: left sidebar is empty.
  • .../testE/building-examples.html
• F: .../testF/#: same as E, empty.
  • .../testF/building-examples.html
• G: .../testG/#: same as E, empty.
  • .../testG/building-examples.html
• H: .../testH/index.html#: for some reason, GitHub returns 404...
  • .../testH/building-examples.html

Therefore, it seems that the theme needs to be modified in order to allow globaltoc_depth > 1. Particularly, collapsible items should have two parts:

• The text should keep linking to the corresponding page.
• The caret, and only the caret, should collapse/expand the children.

Alternatively, the theme might be modified so that the depth of the right sidebar is also configurable through theme options. Currently, the left does show children by traversing toctrees, but the right seems to only include sections of the current page, not children traversing toctrees. Then, it would not mind if the items on the left sidebar are not collapsible because all of them would be expanded on the right.

It is surprising that the left sidebar seems to be broken in the latest version of the upstream. It might be related to some recent changes in Sphinx, since the theme was not updated since Oct 2021. Another user reported it: https://github.com/bashtage/sphinx-material/issues/128.

Per https://github.com/f4pga/sphinx_f4pga_theme/commit/2dd4934686b8c5644a1124f1cf5d9d03a34d6c14 and https://github.com/f4pga/sphinx_f4pga_theme/commit/09ae77d684912714e29bb3ea28c9b79c7db1c3c0, maybe @daniellimws can provide some insight?