issue_comments

Before:

After:

Done: https://sqlite-utils.datasette.io/en/latest/reference.html

That fixed it:

Relevant JavaScript: https://github.com/simonw/datasette/blob/1d33fd03b3c211e0f48a8f3bde83880af89e4e69/docs/_static/js/custom.js#L20-L24

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:

I think the trick will be to extend the base.html template from Furo using the same trick I used in https://til.simonwillison.net/readthedocs/custom-sphinx-templates

https://github.com/pradyunsg/furo/blob/2022.04.07/src/furo/theme/furo/base.html - the site_meta block looks good.

One last question: how to include the Plausible analytics?

Furo doesn't have any specific tools for this:

• https://github.com/pradyunsg/furo/discussions/243

I'm going to move my custom JavaScript from layout.html into js/custom.js, similar to how the custom CSS works.

This seems to work for brand.html:

```html+jinja

{% block brand_content %}

{%- set nav_version = version %} {% if READTHEDOCS and current_version %} {%- set nav_version = current_version %} {% endif %} {% if nav_version %}

{{ nav_version }}

{% endif %} {% endblock brand_content %}

```

Oh but rg display_version is a lot more interesting: lib/python3.10/site-packages/sphinx/builders/html/__init__.py:from sphinx import __display_version__, package_dir lib/python3.10/site-packages/sphinx/builders/html/__init__.py: 'sphinx_version': __display_version__, lib/python3.10/site-packages/sphinx/application.py: logger.info(bold(__('Running Sphinx v%s') % sphinx.__display_version__)) lib/python3.10/site-packages/sphinx/application.py: if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__: lib/python3.10/site-packages/sphinx/application.py: if version > sphinx.__display_version__[:3]: lib/python3.10/site-packages/sphinx/cmd/build.py:from sphinx import __display_version__, package_dir lib/python3.10/site-packages/sphinx/cmd/build.py: version='%%(prog)s %s' % __display_version__) lib/python3.10/site-packages/sphinx/cmd/make_mode.py: print(bold("Sphinx v%s" % sphinx.__display_version__)) lib/python3.10/site-packages/sphinx/__init__.py:__display_version__ = __version__ # used for command line version lib/python3.10/site-packages/sphinx/__init__.py: __display_version__ = __version__ lib/python3.10/site-packages/sphinx/__init__.py: __display_version__ += '/' + ret.stdout.strip() lib/python3.10/site-packages/sphinx/ext/githubpages.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/intersphinx.py: 'version': sphinx.__display_version__, lib/python3.10/site-packages/sphinx/cmd/quickstart.py:from sphinx import __display_version__, package_dir lib/python3.10/site-packages/sphinx/cmd/quickstart.py: print(bold(__('Welcome to the Sphinx %s quickstart utility.')) % __display_version__) lib/python3.10/site-packages/sphinx/cmd/quickstart.py: version='%%(prog)s %s' % __display_version__) lib/python3.10/site-packages/sphinx/ext/viewcode.py: 'version': sphinx.__display_version__, lib/python3.10/site-packages/sphinx/util/__init__.py: (sphinx.__display_version__, lib/python3.10/site-packages/sphinx/ext/ifconfig.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/todo.py: 'version': sphinx.__display_version__, lib/python3.10/site-packages/sphinx/ext/doctest.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/autosummary/__init__.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/napoleon/__init__.py:from sphinx import __display_version__ as __version__ lib/python3.10/site-packages/sphinx/ext/autosummary/generate.py:from sphinx import __display_version__, package_dir lib/python3.10/site-packages/sphinx/ext/autosummary/generate.py: version='%%(prog)s %s' % __display_version__) lib/python3.10/site-packages/sphinx/ext/inheritance_diagram.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/imgmath.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/linkcode.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/coverage.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/writers/texinfo.py:from sphinx import __display_version__, addnodes lib/python3.10/site-packages/sphinx/writers/texinfo.py:@*Generated by Sphinx """ + __display_version__ + """.@* lib/python3.10/site-packages/sphinx/ext/graphviz.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/mathjax.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/extlinks.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/apidoc.py:from sphinx import __display_version__, package_dir lib/python3.10/site-packages/sphinx/ext/apidoc.py: version='%%(prog)s %s' % __display_version__) lib/python3.10/site-packages/sphinx/ext/autodoc/type_comment.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/sphinx/ext/autodoc/__init__.py: return {'version': sphinx.__display_version__, 'parallel_read_safe': True} lib/python3.10/site-packages/pip/_internal/models/target_python.py: display_version = None lib/python3.10/site-packages/pip/_internal/models/target_python.py: display_version = '.'.join( lib/python3.10/site-packages/pip/_internal/models/target_python.py: ('version_info', display_version), lib/python3.10/site-packages/sphinx_rtd_theme/theme.conf:display_version = True lib/python3.10/site-packages/sphinx_rtd_theme/layout.html: {%- if theme_display_version %}

Weird, I cannot figure out this theme_display_version thing - I even tried this: bash cd /tmp mkdir s cd s python3 -m venv venv source venv/bin/activate pip install sphinx_rtd_theme cd venv rg theme_display_version And got just that one reference: lib/python3.10/site-packages/sphinx_rtd_theme/layout.html 154: {%- if theme_display_version %}

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 wheresphinx_rtd_theme implements it - {%- if theme_display_version %} - but I can't find where that variable is first set, from searching both that theme and Sphinx itself!

Here's a TIL from when I first customized the layout.html template: https://til.simonwillison.net/readthedocs/custom-sphinx-templates

Note that Furo doesn't use layout.html so I need to completely change how I did that.

Undocumented Sphinx feature: you can add extra classes to a code example like this:

``` .. code-block:: json :class: metadata-json

{
    "databases": {
        "russian-ads": {
            "tables": {
                "display_ads": {
                    "fts_table": "ads_fts",
                    "fts_pk": "id",
                    "searchmode": "raw"
                }
            }
        }
    }
}

``` https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block doesn't mention this.

Filed an issue about the lack of documentation here: - https://github.com/sphinx-doc/sphinx/issues/10461

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?

I'd also like to bring back this stable / latest / version indicator:

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 sidebar/brand.html template based on this:

https://github.com/pradyunsg/furo/blob/0c2acbbd23f8146dd0ae50a2ba57258c1f63ea9f/src/furo/theme/furo/sidebar/brand.html

Putting this in the css/custom.css file seems to work for fixing that logo problem:

css body[data-theme="dark"] .sidebar-logo-container { background-color: white; padding: 5px; opacity: 0.6; }

I have some custom CSS in this file:

https://github.com/simonw/datasette/blob/1465fea4798599eccfe7e8f012bd8d9adfac3039/docs/_static/css/custom.css#L1-L7

I tested and the overflow-wrap: anywhere is still needed for this fix: - #828

The .wy-side-nav-search bit is no longer needed with the new theme.

Now live on https://docs.datasette.io/en/latest/testing_plugins.html

https://docs.datasette.io/en/latest/getting_started.html#follow-a-tutorial

I'm going to add this Sphinx plugin: https://github.com/executablebooks/sphinx-copybutton

I could use https://github.com/pradyunsg/sphinx-inline-tabs for this - recommended by https://pradyunsg.me/furo/recommendations/

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.

https://github.com/simonw/datasette/blob/943aa2e1f7341cb51e60332cde46bde650c64217/docs/_templates/layout.html#L1-L61

One other problem: in dark mode the Datasette logo looks bad:

This helps a bit:

css .sidebar-logo-container { background-color: white; padding: 5px; opacity: 0.6; }

And for those local table of contents, do this:

rst .. contents:: :local: :class: this-will-duplicate-information-and-it-is-still-useful-here

I found a workaround for the no-longer-nested left hand navigation: drop this into _templates/sidebar/navigation.html: ```html+jinja

```

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:

• https://docs.datasette.io/en/stable/installation.html
• https://docs.datasette.io/en/stable/plugin_hooks.html