The default OpenAPI package publication rules do not trigger for us
since we do not ship a static OpenAPI schema. Override the publication
rules to match our needs.

Now that uis/devops/continuous-delivery/ci-templates#93 is closed, we
have a generic OpenAPI generator template. Make use of it.

Closes #22

The common CI pipeline has support for mkdocs-based documentation and so
add a basic generated mkdocs config. Base the mkdocs config on the
config which is likely to land in the copier template to minimise future
disruption.

We need to override some parts of the standard jobs to "inject" the
documentation generated by the OpenAPI templates into them. We also need
to add "fake" index.html files which take the place of the real
documentation which will be injected in.

Add jobs which publish generated OpenAPI clients to GitLab's own package
registry. In time we may add ones which publish directly to npm and/or
PyPI but for the moment keep things simple.

Packages are only published if the git ref name matches a specific
value. By default it is the default branch but it can be customised for
advanced users.

Generate documentation for each of the OpenAPI clients along with
redoc-based documentation for the schema itself. Downstream projects
should arrange to copy this documentation to some appropriate place.

We add generic "document a TypeScript project" and "document a Python
project" jobs along with specialisations for each of the clients we
generate.

All documentation ends up in `OPENAPI_GENERATOR_DOCS_ARTIFACT_DIR` which
can be overridden by consuming projects.

Use the openapi-generator CLI to generate and package a TypeScript
client using axios for HTTP transport and a Python package using urllib3
for transport. The version numbers of the generated packages match the
version number of the generated OpenAPI schema.

As the OpenAPI generator is intended to be generic, we configure a
reasonable set of defaults for generated artefact names, etc. Show how
these can be customised in local configuration to specify alternate
locations for schema files and source packages to be added as release
assets. Add the generated API clients as release assets.

The list of generated clients is supposed to be slightly opaque to the
consuming project so that we may add additional clients over time.
Should that prove troublesome, each client may be explicitly disabled by
setting a generator-specific `..._DISABLED` variable.

The package name is generated from the GitLab project name but can be
overridden. We do so in our case since the project name ("api") is a
little under-descriptive.

As with generation, we support per-client overriding of the package name
which we demonstrate with the Python package.

If the schema hasn't changed, not only is it not worth re-generating
clients but we also won't be able to publish clients using the default
strategy of extracting the version from the schema. (Both PyPI and npm
disallow re-uploading packages with the same version number.)

Use release-it's release assets feature to add the build OpenAPI schema
to the release assets. Formally speaking the location of the OpenAPI
artefacts is not guaranteed and so we explicitly set the location of the
artifacts we use before adding it to the release-it configuration.

Add the start of a re-usable OpenAPI client generation mechanism. Add
two files: one which represents the repository-local customisation and
one which is the re-usable template. Add the start of some documentation
for the template with an eye to moving it to the guidebook.

The general idea is that getting OpenAPI clients *should* be as simple
as including an `openapi.yaml` file in the root of the repository. (Note
the name of the file was chosen because GitLab will automatically render
files so-named with swagger UI.)

For our specific use case we want to generate the schema dynamically and
so allow for this by means of customising an "openapi:schema" job whose
role is to ensure the schema is available to downstream jobs as a CI job
artefact. The default behaviour is simply to copy the schema from the
repository but we override it to use the DRF spectactular Django
management command. We use the `--fail-if-warn` flag to allow this job
to additionally act as a "test" test that schema generation succeeds
without warning.

Add in the plumbing to run the [openapi-generator CLI][1] but only use
it for the moment as an additional "test" job which validates the spec.

[1]: https://openapi-generator.tech/

The template has been written with an eye to adding to the common
pipeline and so that there can be zero configuration required to make
use of it. As such the template follows the rules of the common pipeline
in being "safe" to include with no side-effects unless it's triggered
and all CI variables and artefacts are appropriately namespaced.

Closes #24

commitlint currently runs twice, once as part of a direct job and once
as part of pre-commit. As the direct job fails if the branch is not
rebased to main, we have decided to remove this in favour of running
only in pre-commit, which appears to behave more consistently.

Sets renovate-bot to use semantic commits, and only update on Django LTS
versions.

Also enforces semantic commits by updating gitlab pipeline
versions.