Fix strict Sphinx documentation builds

.github/workflows/test.yml

@@ -25,3 +25,8 @@ jobs:
         run: uv run pytest . --doctest-modules --doctest-glob "README.md"
       - name: Run type checking
         run: uv run mypy .
+      - name: Build documentation
+        if: matrix.python-version == '3.13'
+        run: |
+          uv run sphinx-build -n -W --keep-going -b html docs build/html
+          uv run sphinx-build -n -W --keep-going -b man docs build/man

docs/api.rst

@@ -36,11 +36,9 @@ Post objects
 Handlers
 --------
 
-.. autoclass:: frontmatter.default_handlers.BaseHandler
-    :members: 
+See :doc:`handlers` for the handler API and customization examples:
 
-.. autoclass:: frontmatter.default_handlers.YAMLHandler
-
-.. autoclass:: frontmatter.default_handlers.JSONHandler
-
-.. autoclass:: frontmatter.default_handlers.TOMLHandler
+* :class:`~frontmatter.default_handlers.BaseHandler`
+* :class:`~frontmatter.default_handlers.YAMLHandler`
+* :class:`~frontmatter.default_handlers.JSONHandler`
+* :class:`~frontmatter.default_handlers.TOMLHandler`

docs/conf.py

@@ -30,7 +30,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx"]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -67,7 +69,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -154,7 +156,7 @@
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/index.rst

@@ -6,7 +6,9 @@
 Python Frontmatter
 =====================
 
-.. module:: frontmatter
+.. _module-frontmatter:
+
+.. currentmodule:: frontmatter
 
 `Front matter <https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter>`__
 offers a useful way to add arbitrary, structured metadata to text
@@ -152,4 +154,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

frontmatter/__init__.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 import io
+import os
 import pathlib
 from os import PathLike
 from typing import TYPE_CHECKING, Iterable, TextIO
@@ -196,7 +197,7 @@ def loads(
 
 def dump(
     post: Post,
-    fd: str | PathLike[str] | TextIO,
+    fd: str | os.PathLike[str] | TextIO,
     encoding: str = "utf-8",
     handler: BaseHandler | None = None,
     **kwargs: object,