Switch documentation theme to Furo #1746
Comments
|
A couple of changes I want to make. First, I don't really like the way Furo keeps the in-page titles in a separate menu on the right rather than expanding them on the left. I like this:
Furo wants to do this instead:
I also still want to include those inline tables of contents on the two pages that have them: |
|
I found a workaround for the no-longer-nested left hand navigation: drop this into <div class="sidebar-tree">
{{ toctree(
collapse=True,
titles_only=False,
maxdepth=3,
includehidden=True,
) }}
</div> |
|
And for those local table of contents, do this: .. contents::
:local:
:class: this-will-duplicate-information-and-it-is-still-useful-here |
|
One other problem: in dark mode the Datasette logo looks bad:
This helps a bit: .sidebar-logo-container {
background-color: white;
padding: 5px;
opacity: 0.6;
}
|
|
Need to address other customizations I've made in https://github.com/simonw/datasette/blob/0.62a0/docs/_templates/layout.html - such as Plausible analytics and some custom JavaScript. datasette/docs/_templates/layout.html Lines 1 to 61 in 943aa2e |
|
I have some custom CSS in this file: datasette/docs/_static/css/custom.css Lines 1 to 7 in 1465fea I tested and the The |
|
Putting this in the body[data-theme="dark"] .sidebar-logo-container {
background-color: white;
padding: 5px;
opacity: 0.6;
} |
|
I want the Datasette logo in the sidebar to link to https://datasette.io/ Looks like I can do that by dropping in my own |
|
I'd also like to bring back this stable / latest / version indicator:
|
|
Actually maybe I don't? I just noticed that on other pages on https://docs.datasette.io/en/stable/installation.html the only way to get back to that useful table of context / index page at https://docs.datasette.io/en/stable/index.html is by clicking the tiny house icon. Can I do better or should I have the logo do that? |
|
Here's a TIL from when I first customized the Note that Furo doesn't use |
|
I can't get that thing that displays the version working. https://github.com/readthedocs/sphinx_rtd_theme/blob/9264091087620d421b0804c00937b00980ac3916/sphinx_rtd_theme/layout.html#L154 is where |
|
Weird, I cannot figure out this cd /tmp
mkdir s
cd s
python3 -m venv venv
source venv/bin/activate
pip install sphinx_rtd_theme
cd venv
rg theme_display_versionAnd got just that one reference: |
|
Oh but |
|
This seems to work for <div class="sidebar-brand centered">
{% block brand_content %}
<div class="sidebar-logo-container">
<a href="https://datasette.io/"><img class="sidebar-logo" src="{{ logo_url }}" alt="Datasette"></a>
</div>
{%- set nav_version = version %}
{% if READTHEDOCS and current_version %}
{%- set nav_version = current_version %}
{% endif %}
{% if nav_version %}
<div class="version">
{{ nav_version }}
</div>
{% endif %}
{% endblock brand_content %}
</div> |
|
I'm going to move my custom JavaScript from |
|
One last question: how to include the Plausible analytics? Furo doesn't have any specific tools for this: |
|
I think the trick will be to extend the https://github.com/pradyunsg/furo/blob/2022.04.07/src/furo/theme/furo/base.html - the |
|
Now live at https://docs.datasette.io/en/latest/ - the JavaScript that adds the banner about that not being the stable version doesn't seem to work though. Before:
After:
|
|
Relevant JavaScript: datasette/docs/_static/js/custom.js Lines 20 to 24 in 1d33fd0 |
|
That fixed it:
|
https://github.com/pradyunsg/furo
I just did this for
shot-scraperand I really like it: https://shot-scraper.datasette.io/en/latest/The text was updated successfully, but these errors were encountered: