This package is maintained with git-buildpackage(1). It follows DEP-14 for
branch naming (e.g. using debian/master for the current version in Debian
unstable due Debian Python team policy).

It uses pristine-tar(1) to store enough information in git to generate bit
identical tarballs when building the package without having downloaded an
upstream tarball first.

When working with patches it is recommended to use "gbp pq import" to import
the patches, modify the source and then use "gbp pq export --commit" to commit
the modifications.

The changelog is generated using "gbp dch" so if you submit any changes don't
bother to add changelog entries but rather provide a nice git commit message
that can then end up in the changelog.

It is recommended to build the package with pbuilder using:

    gbp buildpackage --git-pbuilder

For information on how to set up a pbuilder environment see the git-pbuilder(1)
manpage. In short:

    DIST=sid git-pbuilder create
    gbp clone https://salsa.debian.org/python-team/packages/mkdocstrings.git
    cd mkdocstrings
    gbp buildpackage --git-pbuilder

While writing we packaged version 0.17.0, while 0.18.1 was also already
released.
The reasoning why not the most recent version was chosen to package is
related to a new experimental Python handler in v0.18.x [1] which was
introduced by upstream.
Some projects which use mkdocstrings to create documentation did have some
trouble with this new features. Once these are fixed newer upstream versions
can be packaged.


Additional notes:
Upstream is using PDM [2] as package build system, this tool hasn't been
packaged for Debian yet. To get the package created by the existing build
tools in Debian the pyproject.toml is getting modified by a patch to use
Poetry as backend to build the package.

The downside on this doing is that the version for the package is set by
debian/rules by using the sed command which can be flaky.
Also on every new upstream version the package dependencies and the version
of these need to get some review to build correct metadata for the package
installation!

[1] https://mkdocstrings.github.io/python/
[2] https://github.com/pdm-project/pdm


 -- Carsten Schoenert <c.schoenert@t-online.de>  Sun, 10 Mar 2022 07:43:00 +0200
