No article TOC/index scrolling for Python elements

[Vegebutcher]

In my testing environment the Sphinx-Immaterial version of docs for our Python API has an issue with the right-side TOC panel: it doesn't scroll and is locked at approx. 1/3rd of the list of available Python methods. As I can see from the template docs in the Customization section, this index scrolls smoothly, when its elements are derived from headings.

[2bndy5]

What browser are you testing with?

I noticed that Firefox doesn't scroll certain menus when the mouse first hovers over the menu; I have to wiggle the mouse over the desired menu for it scroll. This experience isn't specific to sphinx-immaterial theme.

The customization page of the docs uses only 2 or 3 explicit headings. Everything else is declared using a custom-defined confval directive. So, maybe that page isn't the best to compare to. Try the doc's demo API page for comparison.

[Vegebutcher]

Both Chrome and Firefox don't allow scrolling in this pane. Scrolling on your demo API page works, but the index consists of both headings (C++ API, JavaScript API etc.) and Python elements. I wonder if it still worked, when no headings were there, only Python elements.

[2bndy5]

It would be easier to help you troubleshoot if you shared a copy of your docs. This can be done either via RTD (as a separate branch build) or via uploading a zip of your built docs to a comment here.

[2bndy5]

BTW, it looks like your API doc uses a mix of headings and autodoc directives. So, I don't think the problem is specific to python API entries.

For reference, the generated page's secondary toc should be using a CSS rule like so:

.md-sidebar__scrollwrap {
	-webkit-backface-visibility: hidden;
	backface-visibility: hidden;
	margin: 0 .2rem;
	overflow-y: auto;
	scrollbar-color: var(--md-default-fg-color--lighter) transparent;
	scrollbar-width: thin;
}

[Vegebutcher]

The original docs are hosted on RTD and I did the immaterial build locally, so here it is zipped: build.zip

[2bndy5]

Well, it does scroll, but not until you hit the bottom of the body. The secondary toc will still work for mobile browsers as that nav menu get moved to inside the main nav menu.

Upon further inspection, it looks like the secondary toc does not get an inline style="height:<page_height>;" attribute.

Your html:

<div class="md-sidebar__scrollwrap">

when it should be

<div class="md-sidebar__scrollwrap" style="height: 432px;">

note that height is calculated dynamically. 432 is just my browser's current viewport's height.

I'm guessing the console's error msgs about index.ts is what prevents the inline style from being added:

Uncaught TypeError: n is undefined
    o index.ts:97
    RxJS 41
    Wa index.ts:106
    hi index.ts:142
    ls bundle.ts:173
    <anonymous> bundle.ts:173
    <anonymous> bundle.ts:246
index.ts:97:10
    o index.ts:97
    RxJS 41
    Wa index.ts:106
    hi index.ts:142
    ls bundle.ts:173
    map self-hosted:221
    <anonymous> bundle.ts:173
    <anonymous> bundle.ts:246

And JS is where my expertise ends. Calling in the big guns @jbms

[jbms]

Yes, it appears that a javascript error while loading the page leads to the page ending up a broken state where scrolling does not work.

The underlying javascript error appears to be happening here:

sphinx-immaterial/src/assets/javascripts/components/palette/index.ts

Line 97 in 191bc36

scheme: input.getAttribute("data-md-color-scheme"),

I think the issue is that you have specified the "palette" entry of html_theme_options as an empty list. I think it should either be a non-empty list, or a dict, but not an empty list. We should probably document that requirement.

[2bndy5]

I think the issue is that you have specified the "palette" entry of html_theme_options as an empty list. I think it should either be a non-empty list, or a dict, but not an empty list. We should probably document that requirement.

I also found (in testing) that if palette list has only 1 entry, then, IIRC, the primary/accent colors defaulted to black/white. I hadn't looked into since... it was a while back.

@Vegebutcher I had documented what config works in the customization page's palette option. If that seems incomplete, there is a literal code block outlining the theme's current configuration at the bottom of the docs' landing page

[Vegebutcher]

I know the palette options very well from the original Material for MkDocs. I haven't used any customization here yet, since it was just a test of the template. I'm going to do that today. I wonder if I can port CSS settings from our M4MkDocs site at docs.gog.com to make the two look identical.

[Vegebutcher]

OK, after adding theme options including the palette section, the index in the right pane now is cleared and displays just 4 headings. I wonder why Python elements aren't included anymore, while on the next page they are:

Is it related to the mixture of headings and autodoc directives you mentioned, @2bndy5 ?

BTW, is it possible to override the default CSS settings with a custom file, just like in M4MkDocs? html_css_files perhaps? Then I could simply copy my custom stylesheet directly from M4MkDocs…

[2bndy5]

Is it related to the mixture of headings and autodoc directives you mentioned, @2bndy5 ?

No. This is expected behavior. The secondary toc is specific to the page in focus. The primary toc is the site outline. I think the behavior you're looking for is a feature called toc.integrate.

BTW, is it possible to override the default CSS settings with a custom file, just like in M4MkDocs? html_css_files perhaps?

Yes, exactly. If you're not familiar with Sphinx, then you should find the info you need about custom CSS files from the sphinx-doc site.

[jbms]

If you can point us to a branch in your repository that contains the theme config and everything needed to reproduce the issue you are seeing, we can try to take a look.

There are various theme options that affect the table of contents.

[Vegebutcher]

No. This is expected behavior. The secondary toc is specific to the page in focus. The primary toc is the site outline. I think the behavior you're looking for is a feature called toc.integrate.

I know the difference between the two. I was wondering why the right-hand index ("in this article" or localtoc) shows only headings on one page, but on the other it does display the Python elements as well.

Yes, exactly. If you're not familiar with Sphinx, then you should find the info you need about custom CSS files from the sphinx-doc site.

I know Sphinx to some extent, but its docs don't cover this particular subject comprehensively. And after I have used these URLs:

html_favicon = "https://docs.gog.com/_assets/Favicon_Galaxy_32x32@2x.png"

html_logo = "https://docs.gog.com/_assets/galaxy_icon_rgb.svg"

html_css_files = "https://docs.gog.com/stylesheets/gog.css"

the docs don't use the logo nor the custom styling and the mode switch doesn't work (although palettes for both modes are declared properly as light and dark).

@jbms Unfortunately, I'm testing this locally; the changes to the conf.py file are not committed to the source repo. But I can embed this file here if you want.

[jbms]

It would help if you can post your complete set of source files so that I can attempt to build your documentation exactly the same as you have done, in order to understand what is going wrong. One easy way to share it is to just push your changes to a separate branch in your repository. You can delete that branch later once the issue is resolved. Or you could upload a zip file containing the complete set of sources here.

[Vegebutcher]

Here's the repo of the API: /~https://github.com/gogcom/galaxy-integrations-python-api
The only changes I made so far are in the attached conf.py file.

[jbms]

The reason for the missing local TOC entries was that currently local TOC entries are extracted from the global TOC, and are therefore subject to globaltoc_depth, which you had set to 2. Removing that option (which leaves the depth unlimited) fixes that problem. Probably that option should be removed from the theme altogether, since I don't think it is particularly useful.

As for the CSS issues, html_css_files should be a list, not a single string.

As for the favicon and logo, I see that the generated HTML ends up with:

_static/https://docs.gog.com/_assets/galaxy_icon_rgb.svg

_static/https://docs.gog.com/_assets/Favicon_Galaxy_32x32@2x.png

I guess we need to fix the path resolution logic there to also support URLs, rather than just local paths.

[Vegebutcher]

Well, the magic of making a list instead of a single string worked! All styles are now properly imported and the mode toggle works again. Thanks for the tip!

I can put the favicon and logo locally, but I wanted to rely on one place where they are available and always up to date. So yes, supporting URLs would be welcome (as it is in Sphinx since 4.0).

The only issue left is the default font. Neither Sphinx docs, nor your Customization guide provide any information on that. How can I declare a custom font such as Lato? In M4MkDocs it's simply a YAML entry.

[Vegebutcher]

OK, after some trials and errors, I managed to change the font, but found another bug in the theme docs: in the New blocks section there's a description of a block responsible for substituting the default font. But it should read fonts instead of font – I realised that only after reading the code of the default layout.html file here in the repo.

Also, why are there dashes (-) in block declarations in the code sample for layout.html?

{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}

For me, a total Jinja newbie, it was really confusing and misleading.

[2bndy5]

The new blocks section of them docs is an untouched section inherited from sphinx-material theme's docs. I'd like to know what you used from that info and what worked out didn't work (specifically).

why are there dashes (-) in block declarations in the code sample for layout.html?

As you guessed, it is jinja specific syntax. IIRC, the - removes the resulting whitespace in the generated results. Placing - at the beginning or end of a jinja statement will remove the whitespace in the beginning or end.

[2bndy5]

BTW, it would be easier for us to track what changes should be made if you use separate issues. This issue got a little sidetracked because the solution for the problem in the OP was unrelated to your original presumption.

[Vegebutcher]

Sorry for this! I'll make a separate issue report.

[2bndy5]

@Vegebutcher its all good. I do appreciate your feedback as it very valuable from a developer's stand-point. Sorry If my last post seemed brutish.

[Vegebutcher]

No harm done, no hard feelings 😄

[2bndy5]

Just to sum up the suggested changes from this thread:

1. fix palette docs; see above comment
2. fix favicon & logo files for external URL paths; see above comment
3. remove globaltoc_depth inherited from sphinx-material theme; see same comment from point 2.

[2bndy5]

@jbms I'm working on making these suggested changes into a PR... In examining the globaltoc_depth, I ran across the globaltoc_includehidden option. Is it ok if I get rid of this as well (making it always True)?

The globaltoc_includehidden option is one of those annoying/confusing features from the sphinx-material theme.

[jbms]

Yeah I think it is reasonable to also eliminate the globaltoc_includehidden option.