From 9e6aa00c4dab6857acb598f4b9363556f85a3755 Mon Sep 17 00:00:00 2001 From: Ryan Chou <88779759+ryanchou1994@users.noreply.github.com> Date: Wed, 9 Sep 2026 07:48:52 +0800 Subject: [PATCH] Fix strict Sphinx documentation builds Keep handler descriptions in one location, resolve Python type links, and check HTML and man output in CI. --- .github/workflows/test.yml | 5 +++++ docs/api.rst | 12 +++++------- docs/conf.py | 8 +++++--- docs/index.rst | 5 +++-- frontmatter/__init__.py | 3 ++- 5 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 8791fc5..bdc5f44 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/docs/api.rst b/docs/api.rst index 7580b59..7bc1ed2 100644 --- a/docs/api.rst +++ b/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` diff --git a/docs/conf.py b/docs/conf.py index 1b0fecd..1329a61 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 874977d..b818e29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,9 @@ Python Frontmatter ===================== -.. module:: frontmatter +.. _module-frontmatter: + +.. currentmodule:: frontmatter `Front matter `__ offers a useful way to add arbitrary, structured metadata to text @@ -152,4 +154,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/frontmatter/__init__.py b/frontmatter/__init__.py index 04f4029..f2fd418 100644 --- a/frontmatter/__init__.py +++ b/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,