ENH: adding sphinx sidebars functionality #248
Conversation
choldgraf
force-pushed
the
custom_sidebars
branch
from
b2d2110
to
cc552c0
Compare
|
ping to @jorisvandenbossche - let me know if you want me to self-merge this kinda thing but I feel like it's good practice to have at least another pair of 👀 on things... |
docs/user_guide/configuring.rst
Outdated
|
|
||
| ``pydata_sphinx_theme`` provides two new sidebar items by default: | ||
|
|
||
| - ``nav-bs.html`` - a bootstrap-friendly navigation section |
There was a problem hiding this comment.
Maybe can use some more clear name like sidebar-nav ? (Because "nav" could also be about the navbar)
There was a problem hiding this comment.
The "bs" is for bootstrap I suppose? (in my head it's "boots-trap", but I realize now that is wrong :-))
There was a problem hiding this comment.
yep, I figured the bs- makes sense just to make it clear that it's a theme-specific thing. I guess we could also use pydata-sidebar-nav or something? Though if you're fine with bs- I'd probably just stick with that...
There was a problem hiding this comment.
what would you like me to do here? do you prefer a re-name? Are you 👍 on sidebar-nav-bs?
There was a problem hiding this comment.
I updated this to sidebar-nav-bs and the search one to sidebar-search-bs in case that's what you wanted, LMK if you prefer something different
There was a problem hiding this comment.
Yep, let's not be too picky about the names;)
| # Update templates for sidebar | ||
| pkgdir = os.path.abspath(os.path.dirname(__file__)) | ||
| path_templates = os.path.join(pkgdir, "_templates") | ||
| app.config.templates_path.append(path_templates) |
There was a problem hiding this comment.
just wondering about this one: is there some documentation in sphinx that this is the recommended way to add custom templates as a package?
There was a problem hiding this comment.
hmmm, well it's documented in a way that suggests you could add to it to increase the search scope for templates: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path
and it seems this is how Sphinx adds templates in its own codebase, e.g.: https://github.com/sphinx-doc/sphinx/blob/cc25bac26445688c50efb9b8d5f30571940e27bd/sphinx/ext/autosummary/generate.py#L644
There was a problem hiding this comment.
If that's how they do it for the built-in extensions, that's certainly fine!
jorisvandenbossche
changed the title
|
@choldgraf can you merge master or rebase, seems to be a conflict with theme.conf |
|
done! let's see if tests pass |
See pydata/pydata-sphinx-theme#248 Co-authored-by: Kay Kim <kay.kim@inrupt.com>
See pydata/pydata-sphinx-theme#248 Co-authored-by: Kay Kim <kay.kim@inrupt.com>
Apparently I had time to figure this out after all :-)
This PR makes this theme use the
html_sidebarsfunctionality of Sphinx. The default behavior is the same, but now if users modifyhtml_sidebars, then the results will show up in their site.closes #244 (and maybe addresses some of the other sidebar issues?)
I'm pretty sure the failing test is the same jupyter-sphinx bug @jorisvandenbossche mentioned elsewhere
and see here for a page where I added a custom sidebar! https://pydata-sphinx-theme--248.org.readthedocs.build/en/248/contributing.html