Use mkdocs 1.2.1

[madwort]

I suspect that upgrading mkdocs & mkdocstrings at the same time might fix CI - let's see.

[cloudflare-pages]

Deploying with    Cloudflare Pages

Latest commit:	2fbba42
Status:	🚫  Build failed.

View logs

[StevenMaude]

To solve that problem, add

site_url: https://docs.opensafely.org

in mkdocs.yml

Then this will result in:

  File "templates/python/material/parameters.html", line 14, in top-level template code
    <td>{{ parameter.description|convert_markdown }}</td>
TypeError: do_convert_markdown() missing 1 required positional argument: 'heading_level'

Which I don't understand why it's required yet:

https://github.com/mkdocstrings/mkdocstrings/blob/87c55fb07cb54e9899c4dee7070da38d6a9ce797/src/mkdocstrings/handlers/base.py#L141

[madwort]

thanks, added a separate mkdocs.test.yml, because I wanted to avoid breaking links on the cloudflare test deploys - it gives the error that the mkdocstring pr gives on its own, though - maybe we can fix that there & do mkdocs-1.2 afterwards

[StevenMaude]

This is all resolved now via #332 and #333. In mkdocs 1.2.1 there was a requirement to specify site_url: this requirement was removed in 1.2.2.

---

NB: site_url is to specify a canonical URL. We possibly wouldn't want https://docs.opensafely.org as site_url for local builds or Cloudflare Pages previews, but only for the deployed site.

Cloudflare Pages lets you discern production from non-production branches. If we wanted to do this, I think it would be possible via:

1. Add a script/make target, or similar, to launch mkdocs build --strict.
2. In that wrapper around mkdocs build --strict, check if the Cloudflare Pages-specific environment variable — CF_PAGES_BRANCH — is main.
3. If the branch is main then set a SITE_URL (or similar) environment variable to https://docs.opensafely.org
4. In mkdocs.yml, specify site_name: !ENV SITE_URL — see the mkdocs documentation. If the SITE_URL environment variable is not set, then restore the default.

Alternatively, if it's possible to set custom environment variables for testing and production within Cloudflare Pages, then that would remove the need for the wrapper: we'd just need the !ENV SITE_URL in mkdocs.yml.

[madwort]

Nice!