issue_comments

Got a couple of TILs out of this:

• Promoting the stable version of the documentation using rel=canonical
• Linking from /latest/ to /stable/ on Read The Docs

https://sphinx-version-warning.readthedocs.io/ looks like it can show a banner for "You are looking at v0.36 but you should be looking at 0.40" but doesn't hand the case I need here which is "you are looking at /latest/ but you should be looking at /stable/".

Correction! That tool DOES support that, as can be seen in their example configuration for their own documentation:

https://github.com/humitos/sphinx-version-warning/blob/a82156c2ea08e5feab406514d0ccd9d48a345f48/docs/conf.py#L32-L38

python versionwarning_messages = { 'latest': 'This is a custom message only for version "latest" of this documentation.', } versionwarning_admonition_type = 'tip' versionwarning_banner_title = 'Tip' versionwarning_body_selector = 'div[itemprop="articleBody"]'

https://sphinx-version-warning.readthedocs.io/ looks like it can show a banner for "You are looking at v0.36 but you should be looking at 0.40" but doesn't hand the case I need here which is "you are looking at /latest/ but you should be looking at /stable/".

Just shipped my fix here: https://docs.datasette.io/en/latest/

Or you can use https://sphinx-version-warning.readthedocs.io/! 😄

Here's a jQuery recipe that seems to do the right thing: javascript jQuery(function ($) { // If this is a /latest/ doc page, show banner linking to /stable/ if (!/\/latest\//.test(location.pathname)) { return; } var stableUrl = location.pathname.replace("/latest/", "/stable/"); // Check it's not a 404 fetch(stableUrl, { method: "HEAD" }).then((response) => { if (response.status == 200) { var warning = $( `<div class="admonition warning"> <p class="first admonition-title">Note</p> <p class="last"> This documentation covers the <strong>development version</strong> of Datasette.</p> <p>See <a href="${stableUrl}">this page</a> for the current stable release. </p> </div>` ); warning.find("a").attr("href", stableUrl); var body = $("div.body"); if (!body.length) { body = $("div.document"); } body.prepend(warning); } }); });

Turns out that banner is something that ReadTheDocs implemented - I found it using GitHub code search, it's produced by this piece of JavaScript: https://github.com/readthedocs/readthedocs.org/blob/0852d7c10d725d954d3e9a93513171baa1116d9f/readthedocs/core/static-src/core/js/doc-embed/version-compare.js#L13-L21

```javascript function init(data) { var rtd = rtddata.get();

/// Out of date message

if (data.is_highest) {
    return;
}

var currentURL = window.location.pathname.replace(rtd['version'], data.slug);
var warning = $(
    '<div class="admonition warning"> ' +
    '<p class="first admonition-title">Note</p> ' +
    '<p class="last"> ' +
    'You are not reading the most recent version of this documentation. ' +
    '<a href="#"></a> is the latest version available.' +
    '</p>' +
    '</div>');

warning
  .find('a')
  .attr('href', currentURL)
  .text(data.slug);

var body = $("div.body");
if (!body.length) {
    body = $("div.document");
}
body.prepend(warning);

} ```

And here's where that module is called from the rest of their code: https://github.com/readthedocs/readthedocs.org/blob/bc3e147770e5740314a8e8c33fec5d111c850498/readthedocs/core/static-src/core/js/doc-embed/footer.js#L66-L86

I'm tempted to imitate their JavaScript but check for /latest/ in the URL and use that to append a similar message warning about this being the documentation for the in-development version.

Huh, I had forgotten I already have a banner on older versions:

Might want to consider SEO here too - I want people from search engines to land on /stable/, I wonder if I should noindex or rel=canonical the other documentation versions? Not sure what best practices for that is.

I think I want a banner at the top of the page making it obvious which version the documentation is talking about. This can be pretty low key for the current stable release, but should be visually more prominent for the /latest/ branch and for older releases.

Wrote up a TIL: https://til.simonwillison.net/pixelmator/pixel-editing-favicon

Resized it down to 208 bytes with https://squoosh.app

Here's a comparison between my hand-edited version and the one I have now:

The new 32x32 image:

One last go at tidying this up. I decided to do a 32x32 pixel version in Pixelmator, using this trick to access a pixel brush: https://osxdaily.com/2016/11/17/enable-pixel-brush-pixelmator-mac/

Frustrating how the white boxes are all exactly four pixels high and ALMOST all four pixels wide, but one of them has to be three pixels wide to fit the space.

Now live on https://latest.datastte.io/ - I'm happy enough with this for the moment:

Oops, I pushed the one I liked least out of the two options! Fixing now.

New favicon now live on https://latest.datasette.io/ - see also https://latest.datasette.io/favicon.ico

The new /favicon.ico view: https://github.com/simonw/datasette/blob/0467723ee57c2cbc0f02daa47cef632dd4651df0/datasette/app.py#L182-L192

My attempt with one less grid line looked awful when shrunk down to the browser size:

File here:

I'm going with the first attempt for the moment.

I'm not crazy about the look - I think this version of the grid may have too many lines for this particular display size.

I'm going to try reducing the number of lines in Figma to see if I like that better. https://www.figma.com/file/LKjceTFNtKm6wCbScDqm1Y/Datasette-Logo

Here's what it looks like in Firefox, Chrome and Safari:

I'm going to drop it in datasette/static/favicon.png and rewrite the async def favicon() function to return it, with caching headers.

Here's the 128x128 one - 11kb, I resized it using Preview:

Now running it through Squoosh using OxiPNG effort=3 colours=24 - brought it down to 1.36KB.

https://adamj.eu/tech/2022/01/18/how-to-add-a-favicon-to-your-django-site/ suggests 64x64, I'm going with 128x128 just in case anyone invents a retina-retina screen.

This one is 101KB and 1536*1536 which is a bit big! https://github.com/simonw/datasette-app/blob/main/build/icon.png

Fixed: https://docs.datasette.io/en/latest/plugins.html#seeing-what-plugins-are-installed

I don't have solid tests in place for exercising SpatiaLite, but this change feels safe enough that I'm not going to add tests for it.

Dropped support for Python 3.6: updated setup.py, changed all references in the documentation to say 3.7 is the minimum required version, got rid of the GitHub Actions tests against 3.6.

OK, now that Uvicorn has dropped 3.6 support - see #1606 - I think this decision is easy to make. I'm dropping 3.6.

Relevant: - https://github.com/simonw/datasette/issues/1577

https://pypistats.org/packages/datasette shows Python 3.6 is 0.24% of Datasette downloads.

https://github.com/simonw/latest-datasette-with-all-plugins/commit/1e12ffe70be791e3281b41810e837515314c1317 shows that 5 days ago Datasette upgraded from Uvicorn 0.16 to 0.17

Sure enough, in the changelog for 0.17: https://github.com/encode/uvicorn/blob/0.17.0/CHANGELOG.md

• Drop Python 3.6 support (#1261) 06/01/22

I need to add sqlite_stat1 to the hidden tables too, see: - https://github.com/simonw/datasette/issues/1587 - https://github.com/simonw/sqlite-utils/issues/366

Oh interesting, I hadn't heard about KNN2. It looks like it was added to SpatiaLite on 21st June 2021 in https://www.gaia-gis.it/fossil/libspatialite/info/03786a62cdb4ab17 but the most recent release of SpatiaLite is 5.0.1 from 7th February 2021 - so it's not yet in a release.

A problem with this is that if you're using --query you likely want ALL of the results - at the moment the only Datasette output type that can stream everything is .csv and plugin formats can't handle full streams, see #1062 and #1177.

I figured out a neat pattern for streaming JSON arrays in this TIL: https://til.simonwillison.net/python/output-json-array-streaming

Right now, I usually have a line in a Makefile like this:

make combined.geojson: project.db pipenv run datasette project.db --get /project/combined.geojson \ --load-extension spatialite \ --setting sql_time_limit_ms 5000 \ --setting max_returned_rows 20000 \ -m metadata.yml > $@

That all assumes I've loaded whatever I need into project.db and created a canned query called combined (and then uses datasette-geojson for geojson output).

It works, but as you can see, it's a lot to manage, a lot of boilerplate, and it wasn't obvious how to get there. If there's an error in the canned query, I get an HTML error page, so that's hard to debug. And it's only one query, so each output needs a line like this. Make isn't ideal, either, for that reason.

The thing I really liked with datafreeze was doing templated filenames. I have a project now where I need to export a bunch of litttle geojson files, based on queries, and it would be awesome to be able to do something like this:

yml databases: project: queries: boundaries: sql: "SELECT * FROM boundaries" filename: "boundaries/{id}.geojson" mode: "item" format: geojson

And then do:

sh datasette freeze -m metadata.yml project.db

For HTML export, maybe there's a template argument, or format: template or something. And that gets you a static site generator, kinda for free.