Update documentation build and CI configuration (#1205)

First steps towards #1203

.github/workflows/tests.yml

@@ -1,3 +1,7 @@
+# This file configures the continuous integration (CI) system on GitHub.
+# Introductory materials can be found here: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions.
+# Documentation for editing this file can be found here: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+
 name: Tests
 
 on:
@@ -8,49 +12,48 @@ on:
 
 jobs:
   lint:
-    name: Lint
+    name: Code Quality
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: [ "3.12", "3.9" ]
+        tox-command: ["manifest", "lint", "pyroma", "mypy"]
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: "Install uv"
+        uses: "astral-sh/setup-uv@v3"
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: "Run command"
         run: |
-          pip install tox tox-uv
-      - name: Check manifest
-        run: tox -e manifest
-      - name: Check code quality with flake8
-        run: tox -e flake8
-      - name: Check package metadata with Pyroma
-        run: tox -e pyroma
-      - name: Check static typing with MyPy
-        run: tox -e mypy
+          uvx -p ${{ matrix.python-version }} --with tox-uv tox -e ${{ matrix.tox-command }}
+
   docs:
     name: Documentation
     runs-on: ubuntu-latest
     strategy:
       matrix:
+        # We only test documentation on the latest version
+        # sphinx 8.0 / sphinx-rtd-theme 3.0 discontinued Python 3.9 support
+        # a year early, which prompted re-thinking about this.
         python-version: [ "3.12" ]
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: "Install uv"
+        uses: "astral-sh/setup-uv@v3"
         with:
-          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
       - name: Install dependencies
         run: |
-          pip install tox tox-uv
+          sudo apt-get install graphviz
       - name: Check RST conformity with doc8
-        run: tox -e doc8
+        run: uvx -p ${{ matrix.python-version }} --with tox-uv tox -e doc8
       - name: Check docstring coverage
-        run: tox -e docstr-coverage
+        run: uvx -p ${{ matrix.python-version }} --with tox-uv tox -e docstr-coverage
       - name: Check documentation build with Sphinx
-        run: tox -e docs-test
+        run: uvx -p ${{ matrix.python-version }} --with tox-uv tox -e docs-test
   tests:
     name: Tests
     runs-on: ${{ matrix.os }}
@@ -60,22 +63,17 @@ jobs:
         python-version: [ "3.12", "3.9" ]
         pydantic: [ "pydantic1", "pydantic2" ]
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - name: "Install uv"
+        uses: "astral-sh/setup-uv@v3"
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          pip install tox tox-uv
-      - name: Test with pytest
-        run:
-          tox -e py-${{ matrix.pydantic }}
-      - name: Doctests
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Test with pytest and generate coverage file
         run:
-          tox -e doctests
+          uvx -p ${{ matrix.python-version }} --with tox-uv tox -e py-${{ matrix.pydantic }}
       - name: Upload coverage report to codecov
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v4
         if: success()
         with:
           file: coverage.xml

docs/source/conf.py

@@ -1,17 +1,16 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+"""
+Configuration file for the Sphinx documentation builder.
 
-# -- Path setup --------------------------------------------------------------
+This file does only contain a selection of the most common options. For a
+full list see the documentation:
+http://www.sphinx-doc.org/en/master/config
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+-- Path setup --------------------------------------------------------------
+
+If extensions (or modules to document with autodoc) are in another directory,
+add these directories to ``sys.path`` here. If the directory is relative to the
+documentation root, use ``os.path.abspath`` to make it absolute, like shown here.
+"""
 
 import os
 import re
@@ -31,13 +30,26 @@
 
 # The short X.Y version.
 parsed_version = re.match(
-    "(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(?P<build>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?",
+    r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(?P<build>[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?",
     release,
 )
-version = parsed_version.expand("\g<major>.\g<minor>.\g<patch>")
+version = parsed_version.expand(r"\g<major>.\g<minor>.\g<patch>")
 
 if parsed_version.group("release"):
-    tags.add("prerelease")
+    tags.add("prerelease")  # noqa: F821
+
+
+# See https://about.readthedocs.com/blog/2024/07/addons-by-default/
+# Define the canonical URL if you are using a custom domain on Read the Docs
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# See https://about.readthedocs.com/blog/2024/07/addons-by-default/
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    if "html_context" not in globals():
+        html_context = {}
+    html_context["READTHEDOCS"] = True  # noqa: F821
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -80,7 +92,9 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+}
 
 # The master toctree document.
 master_doc = "index"
@@ -137,7 +151,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "Bioregistrydoc"
+htmlhelp_basename = "bioregistry_doc"
 
 # -- Options for LaTeX output ------------------------------------------------
 
@@ -225,10 +239,18 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
+# Note: don't add trailing slashes, since sphinx adds "/objects.inv" to the end
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "rdflib": ("https://rdflib.readthedocs.io/en/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
 }
 
 autoclass_content = "both"
+
+# Don't sort alphabetically, explained at:
+# https://stackoverflow.com/questions/37209921/python-how-not-to-sort-sphinx-output-in-alphabetical-order
 autodoc_member_order = "bysource"
+
+todo_include_todos = True
+todo_emit_warnings = True

pyproject.toml

@@ -1,7 +1,7 @@
 # See https://setuptools.readthedocs.io/en/latest/build_meta.html
 [build-system]
 requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta:__legacy__"
+build-backend = "setuptools.build_meta"
 
 [tool.black]
 line-length = 100

setup.cfg

@@ -73,8 +73,8 @@ tests =
     httpx
 docs =
     # see https://github.com/mansenfranzen/autodoc_pydantic/issues/255
-    sphinx<7.3
-    sphinx-rtd-theme
+    sphinx>=8.0
+    sphinx-rtd-theme>=3.0
     sphinx-click
     sphinx_automodapi
     autodoc_pydantic

src/bioregistry/resource_manager.py

@@ -293,8 +293,6 @@ def parse_uri(self, uri: str, *, use_preferred: bool = False) -> MaybeCURIE:
         >>> manager.parse_uri("https://www.ebi.ac.uk/ols/ontologies/ecao/terms?iri=http://purl.obolibrary.org/obo/ECAO_0107180")  # noqa:E501
         ('ecao', '0107180')
 
-        .. todo:: IRI from bioportal
-
         IRI from native provider
 
         >>> manager.parse_uri("https://www.alzforum.org/mutations/1234")
@@ -338,8 +336,6 @@ def parse_uri(self, uri: str, *, use_preferred: bool = False) -> MaybeCURIE:
 
         >>> manager.parse_uri("https://omim.org/MIM:PS214100")
         ('omim.ps', '214100')
-
-        .. todo:: IRI with weird embedding, like ones that end in .html
         """
         prefix, identifier = self.converter.parse_uri(uri)
         if prefix is None or identifier is None:
@@ -368,8 +364,6 @@ def compress(self, uri: str, *, use_preferred: bool = False) -> Optional[str]:
         >>> manager.compress("https://www.ebi.ac.uk/ols/ontologies/ecao/terms?iri=http://purl.obolibrary.org/obo/ECAO_1")  # noqa:E501
         'ecao:1'
 
-        .. todo:: URI from bioportal
-
         URI from native provider
 
         >>> manager.compress("https://www.alzforum.org/mutations/1234")
@@ -667,7 +661,7 @@ def get_converter(
         from .record_accumulator import get_converter
 
         # first step - filter to resources that have *anything* for a URI prefix
-        # TODO maybe better to filter on URI format string, since bioregistry can always provide a URI prefix
+        # maybe better to filter on URI format string, since bioregistry can always provide a URI prefix
         resources = [
             resource for _, resource in sorted(self.registry.items()) if resource.get_uri_prefix()
         ]
@@ -1101,7 +1095,6 @@ def get_bioportal_iri(self, prefix: str, identifier: str) -> Optional[str]:
         obo_link = self.get_obofoundry_iri(prefix, identifier)
         if obo_link is not None:
             return f"https://bioportal.bioontology.org/ontologies/{bioportal_prefix}/?p=classes&conceptid={obo_link}"
-        # TODO there must be other rules?
         return None
 
     def get_ols_iri(self, prefix: str, identifier: str) -> Optional[str]: