docs: generate and publish API documentation

.github/workflows/ci.yml

@@ -25,3 +25,16 @@ jobs:
           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

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