Migrate to copier-based swh-py-template and normalize the README file

.copier-answers.yml

+# Changes here will be overwritten by Copier
+_commit: v0.1.6
+_src_path: https://gitlab.softwareheritage.org/swh/devel/swh-py-template.git
+description: Software Heritage Documentation
+distribution_name: swh-docs
+have_cli: false
+have_workers: false
+package_root: swh/docs
+project_name: swh.docs
+python_minimal_version: '3.7'
+readme_format: rst

.gitignore

+*.egg-info/
+*.pyc
+.coverage
+.eggs/
+.hypothesis
+.mypy_cache
+.tox
+__pycache__
 build/
-/.eggs/
-/.tox/
-/swh.docs.egg-info/
-/swh/__pycache__/
-/swh/docs/__pycache__/
-/swh/docs/sphinx/__pycache__/
-/version.txt
-apidoc/
-docs/README.*
+dist/
+# these are symlinks created by a hook in swh-docs' main sphinx conf.py
+docs/README.rst
+docs/README.md
+# this should be a symlink for people who want to build the sphinx doc
+# without using tox, generally created by the swh-env/bin/update script
+docs/Makefile.sphinx

.pre-commit-config.yaml

 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: trailing-whitespace
       - id: check-json
       - id: check-yaml
 
+  - repo: https://github.com/python/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+
   - repo: https://github.com/pycqa/flake8
-    rev: 5.0.4
+    rev: 6.0.0
     hooks:
       - id: flake8
         additional_dependencies: [flake8-bugbear==22.9.23]
@@ -17,8 +27,10 @@ repos:
     hooks:
       - id: codespell
         name: Check source code spelling
-        args: [-L aks, -L crate]
         stages: [commit]
+      - id: codespell
+        name: Check commit message spelling
+        stages: [commit-msg]
 
   - repo: local
     hooks:
@@ -30,12 +42,3 @@ repos:
         language: system
         types: [python]
 
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.11.5
-    hooks:
-      - id: isort
-
-  - repo: https://github.com/python/black
-    rev: 22.10.0
-    hooks:
-      - id: black

MANIFEST.in

-include Makefile
-include requirements*.txt
-include version.txt

README.md → README.rst

-swh-docs
-========
+Software Heritage Technical Documentation
+=========================================
 
 This module contains (the logics for generating) the Software Heritage
-development documentation.
+technical documentation.
 
 Specifically, it contains some general information about Software Heritage
 internals (stuff that would not fit in any other specific software component of
 the Software Heritage stack) and bundle them together component-specific
 documentation coming from other modules of the stack.
 
-All documentation is written and typeset using [Sphinx][1]. General
+All documentation is written and typeset using Sphinx_. General
 documentation is shipped as part of this module. Module-specific documentation
-is centralized here via symlinks to the `docs/` dirs of individual modules.
+is centralized here via symlinks to the ``docs/`` dirs of individual modules.
 Therefore to build the full documentation you need a working and
-complete [Software Heritage development environment][2].
-
+complete `Software Heritage development environment`_.
 
 
 How to build the doc
 --------------------
 
-Install the [Software Heritage development environment][2]
+Install the `Software Heritage development environment`_:
+
+.. code-block:: shell
+
+   $ git clone https://gitlab.softwareheritage.org/swh/devel/swh-environment.git
+   $ cd swh-environment
+   $ ./bin/update  # this will clone needed git repos, inc. swh-docs
+   $ cd swh-docs
 
-    $ git clone https://gitlab.softwareheritage.org/swh/devel/swh-environment.git
-    $ cd swh-environment
-    $ ./bin/update  # this will clone needed git repos, inc. swh-docs
-    $ cd swh-docs
+Ensure you have the required tools to generate images (graphviz_'s ``dot``,
+plantuml_ and inkscape_). On a Debian system:
 
-Ensure you have the required tools to generate images ([graphviz][3]'s `dot`,
-[plantuml][4] and [inkscape][5]). On a Debian system:
+.. code-block:: shell
 
-    $ sudo apt install plantuml graphviz
+   $ sudo apt install plantuml graphviz
+
+These additional packages are required on Debian 10.x (and newer) systems:
 
-These additional packages are required on Debian 10.x systems:
 - libapr1-dev
 - libaprutil1-dev
 - libsvn-dev
@@ -40,61 +44,74 @@ These additional packages are required on Debian 10.x systems:
 - dia
 - postgresql-autodoc
 
-It is also recommended to build the doc using [tox][6], so ensure you have it
+It is also recommended to build the doc using tox_, so ensure you have it
 installed, eg. on a Debian system:
 
-    $ sudo apt install tox
+.. code-block:: shell
+
+   $ sudo apt install tox
+
 
+Then (from the ``swh-environment/swh-docs/`` directory):
 
-Then (from the `swh-environment/swh-docs/` directory):
+.. code-block:: shell
 
     $ tox run -e sphinx-dev
 
 This tox environment will build the documentation from the sources available in
-the parent directory (`swh-environment`).
+the parent directory (``swh-environment``).
 
 Behind the scene, this tox environment will run the sphinx documentation
-building process via [pifpaf][7] to encapsulate the need os Postgresql to
+building process via pifpaf_ to encapsulate the need os Postgresql to
 generate database schemas. The documentation building process itself consists
 mainly in 3 steps:
 
 ### 1. Generate documentation assets for all modules
 
-    $ cd swh-environment
-    $ pifpaf run postgresql -- make docs-assets
+.. code-block:: shell
 
-This will *not* build the documentation in each module (there is `make docs`
+   $ cd swh-environment
+   $ pifpaf run postgresql -- make docs-assets
+
+This will *not* build the documentation in each module (there is ``make docs``
 for that).
 
 
 ### 2. Build the api docs for all swh python packages
 
-    $ cd swh-docs/docs
-    $ pifpaf run postgresql -- make apidoc
+.. code-block:: shell
+
+   $ cd swh-docs/docs
+   $ pifpaf run postgresql -- make apidoc
 
 ### 3. Build the documentation
 
-    $ cd swh-docs/docs
-    $ make
+.. code-block:: shell
+
+   $ cd swh-docs/docs
+   $ make
 
-The HTML documentation is now available starting from `_build/html/index.html`.
+The HTML documentation is now available starting from
+``_build/html/index.html``.
 
 
 Cleaning up
 -----------
 
-    $ cd docs
-    $ make distclean
+.. code-block:: shell
 
-The former (`make clean`) will only clean the local Sphinx build, without
-touching other modules. The latter (`make distclean`) will also clean Sphinx
+   $ cd docs
+   $ make distclean
+
+The former (``make clean``) will only clean the local Sphinx build, without
+touching other modules. The latter (``make distclean``) will also clean Sphinx
 builds in all other modules.
 
 
 Publishing the doc
 ------------------
 
-The publication of the documentation is now managed by the [CI][7].
+The publication of the documentation is now managed by the CI_.
 
 
 Building standalone package documentation
@@ -105,20 +122,25 @@ Each documentation local to a swh package can also be built with [tox][6].
 For instance to build the standalone documentation of ``swh-web``, proceed as
 follows:
 
-    $ cd swh-environment/swh-web
-    $ tox run -e sphinx-dev
+.. code-block:: shell
+
+   $ cd swh-environment/swh-web
+   $ tox run -e sphinx-dev
 
-Sphinx warnings related to unresolved references located in other swh packages are suppressed because expected.
+Sphinx warnings related to unresolved references located in other swh packages
+are suppressed because expected.
 
 Please also note that Sphinx warnings are turned into errors in that case.
 
-The HTML documentation is now available starting from `docs/_build/html/index.html`.
+The HTML documentation is now available starting from
+``docs/_build/html/index.html``.
 
 
-[1]: http://www.sphinx-doc.org/
-[2]: https://gitlab.softwareheritage.org/swh/devel/swh-environment.git
-[3]: https://graphviz.org
-[4]: http://plantuml.com
-[5]: https://inkscape.org/
-[6]: https://tox.readthedocs.io/
-[7]: https://jenkins.softwareheritage.org/job/DDOC/
+.. _Sphinx: http://www.sphinx-doc.org/
+.. _`Software Heritage development environment`: https://gitlab.softwareheritage.org/swh/devel/swh-environment.git
+.. _graphviz: https://graphviz.org
+.. _plantuml: http://plantuml.com
+.. _inkscape: https://inkscape.org/
+.. _tox: https://tox.readthedocs.io/
+.. _CI: https://jenkins.softwareheritage.org/job/DDOC/
+.. _pifpaf: https://github.com/jd/pifpaf

docs/.gitignore

 *-stamp
 _build/
 devel/swh-*
+errors.log
 !/swh-loader.rst
 sources/
 user/software-origins/dynamic/*.inc
+apidoc/

docs/devel/bin/ln-sphinx-subprojects

@@ -11,7 +11,8 @@ create_links () {
             ln -s "../../../${pymodule}/docs" "$pymodule"
         fi
         if [ -f "$pymodule/images/Makefile" ] ; then
-            make -C $pymodule images
+	    echo "Build images in $pymodule"
+            make -I $PWD/../.. -C $pymodule images
         fi
         if [ -d "../../../${pymodule}/swh" ] ; then
             cp -r -f --symbolic-link $(realpath ../../../${pymodule}/swh/*) sources/swh/
@@ -33,7 +34,7 @@ remove_links () {
             continue
         fi
         if [ -L "$pymodule" ] ; then
-            make -C $pymodule clean
+            make -I $PWD/../.. -C $pymodule clean
             rm "$pymodule"
         fi
     done

mypy.ini

 [mypy]
 namespace_packages = True
 warn_unused_ignores = True
+explicit_package_bases = True
+# ^ Needed for mypy to detect py.typed from swh packages installed
+# in editable mode
 
 # 3rd party libraries without stubs (yet)
 
 [mypy-sphinx.*]
 ignore_missing_imports = True
+
+# [mypy-add_your_lib_here.*]
+# ignore_missing_imports = True

pyproject.toml

+[project]
+name = "swh.docs"
+authors = [
+    {name="Software Heritage developers", email="swh-devel@inria.fr"},
+]
+
+description = "Software Heritage Documentation"
+readme = {file = "README.rst", content-type = "text/x-rst"}
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Operating System :: OS Independent",
+    "Development Status :: 5 - Production/Stable",
+]
+dynamic = ["version", "dependencies", "optional-dependencies"]
+
+[tool.setuptools.packages.find]
+include = ["swh.*"]
+
+[tool.setuptools.dynamic]
+dependencies = {file = ["requirements.txt"]}
+
+[tool.setuptools.dynamic.optional-dependencies]
+testing = {file = ["requirements-test.txt"]}
+building = {file = ["requirements-swh.txt"]}
+
+[project.urls]
+"Homepage" = "https://gitlab.softwareheritage.org/swh/devel/swh-docs"
+"Bug Reports" = "https://gitlab.softwareheritage.org/swh/devel/swh-docs/-/issues"
+"Funding" = "https://www.softwareheritage.org/donate"
+"Documentation" = "https://docs.softwareheritage.org/devel/swh-docs/"
+"Source" = "https://gitlab.softwareheritage.org/swh/devel/swh-docs.git"
+
+[build-system]
+requires = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+fallback_version = "0.0.1"
+
 [tool.black]
 target-version = ['py37']
 
@@ -9,3 +51,4 @@ use_parentheses = true
 ensure_newline_before_comments = true
 line_length = 88
 force_sort_within_sections = true
+known_first_party = ['swh']

pytest.ini

+[pytest]
+norecursedirs = build docs .*
+asyncio_mode = strict
+addopts = "--import-mode=importlib"

requirements-swh-dev.txt

@@ -36,3 +36,4 @@
 ../swh-web
 ../swh-web-client
 ../swh-webhooks
+.

setup.py

-# Copyright (C) 2017-2020  The Software Heritage developers
+# Copyright (C) 2017-2023  The Software Heritage developers
 # See the AUTHORS file at the top-level directory of this distribution
 # License: GNU General Public License version 3, or any later version
 # See top-level LICENSE file for more information
 
-import os
-
-from setuptools import find_packages, setup
-
-
-def parse_requirements(name=None):
-    if name:
-        reqf = "requirements-%s.txt" % name
-    else:
-        reqf = "requirements.txt"
-
-    requirements = []
-    if not os.path.exists(reqf):
-        return requirements
-
-    with open(reqf) as f:
-        for line in f.readlines():
-            line = line.strip()
-            if not line or line.startswith("#"):
-                continue
-            requirements.append(line)
-    return requirements
 
+from setuptools import setup
 
+# TODO: usage of `data_files` is now deprecated; we should find another way of
+# distributing these files.
+#
+# These files are distributed because they are required to build the sphinx
+# documentation of a swh package isolated from the whole swh-development
+# project (esp. as tox target in each swh package; which is e.g. used by the
+# CI).
 setup(
-    name="swh.docs",
-    description="Software Heritage development documentation",
-    python_requires=">=3.7",
-    author="Software Heritage developers",
-    author_email="swh-devel@inria.fr",
-    url="https://gitlab.softwareheritage.org/swh/devel/swh-docs/",
-    packages=find_packages(),
-    scripts=[],
-    install_requires=parse_requirements(),
-    setup_requires=["setuptools-scm"],
-    use_scm_version=True,
-    extras_require={
-        "testing": parse_requirements("test"),
-        "building": parse_requirements("swh"),
-    },
-    include_package_data=True,
     data_files=[
         ("share/swh-docs/docs/devel", ["docs/devel/glossary.rst"]),
         ("share/swh-docs/docs/", ["docs/Makefile"]),

swh/__init__.py

-from pkgutil import extend_path
-
-__path__ = extend_path(__path__, __name__)

tox.ini

 [tox]
-requires =
-  tox>4
-envlist=flake8,black
+minversion = 4
+envlist =
+  black
+  flake8
+  mypy
+  py3
 
 [testenv]
 basepython = python3
@@ -19,22 +22,22 @@ deps =
 setenv =
   SWHPKGDIR = {envsitepackagesdir}/swh
 commands =
-  {envpython} -m pifpaf run postgresql -- make -C docs {posargs:html}
+  {envpython} -m pifpaf run postgresql -- make -I . -C docs {posargs:html}
 
 [testenv:sphinx-dev]
 allowlist_externals = make
-
+skip_install = true
 setenv =
   SWHPKGDIR = {envsitepackagesdir}/swh
 commands =
   # use custom install script for dev build
   make pip-install-swh-dev
-  {envpython} -m pifpaf run postgresql -- make -C docs {posargs:html}
+  {envpython} -m pifpaf run postgresql -- make -I . -C docs {posargs:html}
 
 [testenv:black]
 skip_install = true
 deps =
-  black==22.10.0
+  black==23.1.0
 commands =
   {envpython} -m black --check swh