Comments (26)
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:
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.
from sphinx-immaterial.
No harm done, no hard feelings
from sphinx-immaterial.
Just to sum up the suggested changes from this thread:
- fix
palette
docs; see above comment - fix favicon & logo files for external URL paths; see above comment
- remove
globaltoc_depth
inherited from sphinx-material theme; see same comment from point 2.
from sphinx-immaterial.
Yeah I think it is reasonable to also eliminate the globaltoc_includehidden
option.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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;
}
from sphinx-immaterial.
The original docs are hosted on RTD and I did the immaterial build locally, so here it is zipped: build.zip
from sphinx-immaterial.
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
from sphinx-immaterial.
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
from sphinx-immaterial.
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.
from sphinx-immaterial.
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…
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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/[email protected]"
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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/[email protected]
I guess we need to fix the path resolution logic there to also support URLs, rather than just local paths.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
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.
from sphinx-immaterial.
Sorry for this! I'll make a separate issue report.
from sphinx-immaterial.
@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.
from sphinx-immaterial.
@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.
from sphinx-immaterial.
Related Issues (20)
- Consider switching from MathJax to MathML for math output HOT 3
- Better document globaltoc_collapse HOT 2
- Search missing most content HOT 3
- Does a Python piece of software need to be a package to use python.apigen? HOT 16
- KeyError when trying to build almost empty docs HOT 9
- BUG: LaTeX markers are being stripped from contents HOT 11
- documentation build fails with manpage sphinx builder HOT 16
- 0.11.3: pytest is failing HOT 6
- BUG/ENH: Common Sphinx directives have no style applied HOT 26
- Glossary directive produces 2 permalinks HOT 1
- Editable install no longer runs nodejs build step HOT 4
- Create `myst-example` directive and change documentation to use it HOT 2
- `repo_type` not used and `repo_name` can be intuitive
- New Social Media Card extension HOT 16
- Search missing results HOT 1
- thoughts about a theme logo? HOT 4
- Sphinx will have better support for multi-line python signatures. HOT 4
- pydantic v2.0 breaking custom admonitions HOT 1
- Support for `numpy.typing` HOT 7
- Line block does not preserve indent HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from sphinx-immaterial.