From e4314b700f323e1df0e5b7aae60e427b126c68bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= <snejus@protonmail.com>
Date: Sun, 8 Feb 2026 01:52:23 +0000
Subject: [PATCH] Add rst inline-literal check to lint-docs task

Fail the docs lint task when single-backtick inline literals are used.

This is required because `pandoc` converts:

  `$playlist` -> <span class="title-ref">\$playlist</span>

Where this `span` element has no meaning in markdown context, and
`$playlist` loses its formatting. On the other hand, double backticks
are converted appropriately:

  ``$playlist`` -> `$playlist`
---
 pyproject.toml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 24505d73e..2a0a1904d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -238,7 +238,17 @@ cmd = "ruff check --config=pyproject.toml"
 
 [tool.poe.tasks.lint-docs]
 help = "Lint the documentation"
-shell = "sphinx-lint --enable all --disable default-role $(git ls-files '*.rst')"
+interpreter = "bash"
+shell = """
+set -o pipefail
+files=$(git ls-files '*.rst')
+
+grep -Eno ' `[^`][^`]+`[^_]' $files |
+    sed 's/ .*/ Use double backticks for inline literal (double-backticks-required)/' && failed=1
+sphinx-lint --enable all --disable default-role $files || failed=1
+
+exit ${failed:-0}
+"""
 
 [tool.poe.tasks.update-dependencies]
 help = "Update dependencies to their latest versions."