docs: generate and publish API documentation

.github/workflows/cd.yml

@@ -13,11 +13,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       - name: Install dependencies
         run: pip install .[build]
       - name: Build package

.github/workflows/ci.yml

@@ -10,18 +10,31 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install
         run: pip install .[test,data]
       - name: Run tests
         run: pytest --junitxml=junit/test-results-${{ matrix.python-version }}.xml --cov=language_data --cov-report=xml:junit/coverage-${{ matrix.python-version }}.xml
       - name: Upload 
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: junit-${{ matrix.python-version }}
           path: junit/*
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install tox
+        run: pip install tox
+      - name: Build documentation
+        run: tox -e docs
+

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - data
+    - requirements: docs/requirements.txt

docs/_static/.gitkeep

@@ -0,0 +1 @@
+# Keep docs/_static tracked by git

docs/conf.py

@@ -31,6 +31,7 @@
     'sphinx.ext.autodoc',
     # https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx
     'myst_parser',
+    'sphinx_copybutton',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,7 +48,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_book_theme'
+
+html_theme_options = {
+    "show_navbar_depth": 2,
+    "show_toc_level": 2,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/index.rst

@@ -1,16 +1,12 @@
-.. langcodes documentation master file, created by
-   sphinx-quickstart on Fri Apr 16 21:32:52 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to langcodes's documentation!
-=====================================
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   source/modules
+   self
+   source/langcodes
 
 
 Indices and tables

docs/requirements.txt

@@ -1,2 +1,4 @@
-myst_parser
-
+sphinx
+sphinx-book-theme
+myst-parser
+sphinx-copybutton

docs/source/langcodes.rst

@@ -1,25 +1,9 @@
-langcodes package
+Langcodes package
 =================
 
 Submodules
 ----------
 
-langcodes.build\_data module
-----------------------------
-
-.. automodule:: langcodes.build_data
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-langcodes.data\_dicts module
-----------------------------
-
-.. automodule:: langcodes.data_dicts
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 langcodes.language\_distance module
 -----------------------------------
 
@@ -28,42 +12,11 @@ langcodes.language\_distance module
    :undoc-members:
    :show-inheritance:
 
-langcodes.language\_lists module
---------------------------------
-
-.. automodule:: langcodes.language_lists
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-langcodes.registry\_parser module
----------------------------------
-
-.. automodule:: langcodes.registry_parser
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-langcodes.tag\_parser module
-----------------------------
-
-.. automodule:: langcodes.tag_parser
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-langcodes.util module
----------------------
-
-.. automodule:: langcodes.util
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Module contents
 ---------------
 
 .. automodule:: langcodes
    :members:
    :undoc-members:
    :show-inheritance:
+   :exclude-members: ATTRIBUTES, BROADER_KEYSETS, MATCHABLE_KEYSETS

langcodes/__init__.py

@@ -1833,6 +1833,11 @@ def best_match(
     `min_score` sets the minimum match score. If all languages match with a lower
     score than that, the result will be 'und' with a score of 0.
     """
+    warnings.warn(
+        "`best_match` is deprecated and will be removed in a future version. Please "
+        "use `closest_match` instead.",
+        DeprecationWarning,
+    )
     max_distance = 100 - min_score
     supported, distance = closest_match(
         desired_language, supported_languages, max_distance

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py36, py37, py38, py39, py310, py311, py312
+envlist = py36, py37, py38, py39, py310, py311, py312, p313
 skipsdist = True
 
 [testenv]
@@ -9,3 +9,13 @@ deps =
     language_data
 commands = pip install .
            pytest
+
+[testenv:docs]
+deps =
+    sphinx
+    sphinx-book-theme
+    myst-parser
+    sphinx-copybutton
+    language_data
+commands =
+    sphinx-build -aEWnb html docs docs/build/html