uneven spacing between navbar items

[drammock]

I'm seeing large whitespace in between items of the top navbar that I'm certain isn't meant to be there. Screenshot of our homepage built with 0.4.1:

...and the same page built against current master (ab92898):

The browser console shows that there are many empty li items in between our nav items "tutorials" and "examples":

Any idea what is causing this?

EDIT here's the site: https://github.com/drammock/mne-python/tree/new-website-theme/doc

[jorisvandenbossche]

@drammock cool that you are trying out this theme!

I ran the mne-docs myself as well to check what is happening, and this is caused by the generated auto_tutorials/index.rst having all top-level section headers (instead of 1 main header, and then subsection headers).

This is a bug in the theme (we should filter out those in-page headers from the toctree, because in the navbar we only want links to actual pages).
But a workaround on the short term is to change the headers in the README files in the tutorial subdirectories. I tested it out locally, and that seems to fix it (and since I did it now anyway, pushed the change online -> drammock/mne-python#4, the change can't hurt in any case I think, even when the bug is fixed in the theme)

With that change I get a better result:

This might also befixed by #219, or easier to fix after that PR, but didn't check that

[jorisvandenbossche]

@drammock one additional thing I notice is that, as you can see in my screenshot above, that both "Documentation" and "Tutorials" is highlighted as active in the navbar.

I think this is caused by having the tutorials multiple times in a sphinx toctree. The main index.rst has

.. toctree::
   :hidden:

   Install<install/index>
   Documentation<overview/index>
   Tutorials<auto_tutorials/index>
   Examples<auto_examples/index>
   glossary
   API<python_reference>
   Help<overview/get_help>

but then the overview/index.rst also has:

.. toctree::
   :hidden:

   Tutorials<../auto_tutorials/index>
   Examples<../auto_examples/index>
   ../glossary
   API<../python_reference>

so the tutorial/examples/API appear both in the top-level toctree, as in the "Documentation" sub-toctree.

I would personally advise to put the subpages in the overview/ directory in that sub-toctree instead, which are now included as a manual bullet list:

- :ref:`faq`
- :ref:`migrating`
- :ref:`design_philosophy`
- :ref:`implementation`
- :ref:`datasets`
- :ref:`python_commands`
- :ref:`cookbook`
- :ref:`cite`
- :ref:`roadmap`
- :ref:`whats_new`
- :ref:`general_bibliography`

And on that Documentation overview page, you can still include links to tutorials/examples/API manually.

[drammock]

a workaround on the short term is to change the headers in the README files in the tutorial subdirectories

Awesome, thanks for figuring that out! And for the PR fixing it for me :)

one additional thing I notice is that, as you can see in my screenshot above, that both "Documentation" and "Tutorials" is highlighted as active in the navbar

Yes, I did that on purpose as an experiment, and you are right about the cause (being in the TOC tree twice).

I would personally advise to put the subpages in the overview/ directory in that sub-toctree instead

I want to keep those pages as orphans, because I don't actually want them to show up in the linear order defined by the TOC tree (i.e., I want the next/previous buttons to go straight from the documentation overview to the tutorials page). But I also want tutorials & examples to show up in the top navbar. Thinking back, I think I was motivated by the overview page having an empty sidebar and that looking weird, but I realize now I can just suppress the (empty) sidebar on that page and (I think) the content will get wider. I'll try that.

[jorisvandenbossche]

Ah, I understand the reasoning now. The previous/next buttons are entirely determined by sphinx' toctree structure AFAIK, so I don't think there is an easy way to otherwise get around that.
You could probably override that previous/next block in the template and then check if the pagename is equal overview/index and then insert a different link for the next page. But that might be a bit overkill to achieve that (although certainly possible).

[drammock]

just a note to confirm that your fix worked @jorisvandenbossche; after merging your PR our CIs built a normal-looking top nav: https://24666-1301584-gh.circle-artifacts.com/0/dev/index.html