Add -W option to sphinx-build? (Re: ddp build failed)
Hi,
Richard Lewis <richard.lewis.debian@googlemail.com> wrote (Sat, 31 May 2025 22:19:47 +0100):
> Holger Wansing <hwansing@mailbox.org> writes:
>
> >> > /srv/www.debian.org/release-notes/release-notes/source/issues.rst:: ERROR: Anonymous hyperlink mismatch: 1 references but 0 targets.
> >>
> >> I think this is line 27 which should have `...` around the url (although it's odd that the pipeines never failed for this?)
>
> > And: I think the pipeline did not fail, because this is just a warning
> > (even if it's shown above as an ERROR).
>
> > I have no idea, if this error/warning handling can be adapted ...
>
> It looks like the -W option to sphinx-build turns warnings into errors, so maybe doing
>
> make html SPHINXOPTS="-W"
>
> in .gitlab-ci.yml might work (untested)
Adding -W to all sphinx-build commands in Makefile seems to work
(see diff attached).
A test with an typo like the one mentioned above stops the build with error.
And in fact, building all languages with the -W option uncovers an until now
unvisible error in both chinese langs (zh_CN and zh_TW).
By -W, translators would be made aware of such typos as well, when they
test-build their translation.
So, do we want this change? Any disadvantages to expect?
Holger
--
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
diff --git a/Makefile b/Makefile
index e45cc726..d76025a3 100644
--- a/Makefile
+++ b/Makefile
@@ -90,7 +90,7 @@ text: $(TEXT_FILES)
# Somehow -M doesn't work well, so use -b
$(BUILD_DIR)/%/text/$(PACKAGE).txt: $(SOURCE_FILES)
rm -f $@
- $(SPHINX) -b text -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b text -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
# Make $(PACKAGE).txt
cp $(@D)/index.txt $@
set -e; \
@@ -107,7 +107,7 @@ pdf: $(PDF_FILES)
# Somehow -M doesn't work well, so use -b
$(BUILD_DIR)/%/pdf/$(PACKAGE).pdf: $(SOURCE_FILES)
echo "* Starting pdf build for: $*"
- $(SPHINX) -b latex -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b latex -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
echo "Starting: $(MAKE) -C $(@D)"
$(MAKE) -C $(@D)
@@ -131,7 +131,7 @@ epub: $(EPUB_FILES)
# Somehow -M doesn't work well, so use -b
$(BUILD_DIR)/%/epub/$(PACKAGE).epub: $(SOURCE_FILES)
- $(SPHINX) -b epub -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b epub -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
# A list of info files for all $(LANGS)
# Please note, translated info files are installed as $(PACKAGE)-$(l).info:
@@ -143,7 +143,7 @@ info: $(INFO_FILES)
# Somehow -M doesn't work well, so use -b
$(BUILD_DIR)/%/info/$(PACKAGE).info: $(SOURCE_FILES)
- $(SPHINX) -b texinfo -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b texinfo -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
$(MAKE) -C $(@D)
$(BUILD_DIR)/info/$(PACKAGE).info: $(BUILD_DIR)/en/info/$(PACKAGE).info
@@ -161,7 +161,7 @@ html: $(HTMLI_FILES)
# Somehow -M doesn't work well, so use -b
$(BUILD_DIR)/%/html/index.html: $(SOURCE_FILES)
- $(SPHINX) -b html -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b html -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
# # fixup genindex
find $(BUILD_DIR) -name genindex.html -delete
@@ -180,7 +180,7 @@ singlehtml: $(HTMLS_FILES)
# Single HTML doesn't build its own genindex.html nor search.html
# I keep this code inspired by Debian Policy as a place holder
$(BUILD_DIR)/%/singlehtml/$(PACKAGE).html: $(SOURCE_FILES)
- $(SPHINX) -b singlehtml -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
+ $(SPHINX) -W -b singlehtml -D language=$* -d $(BUILD_DIR)/$* $(SOURCE_DIR) $(@D)
mv $(@D)/index.html $(@D)/$(PACKAGE).html
rm -rf $(@D)/.doctrees
perl -pli -e 's,href="index\.html#,href="#,g' $@
@@ -197,7 +197,7 @@ $(BUILD_DIR)/%/singlehtml/$(PACKAGE).html: $(SOURCE_FILES)
# Hmm, for me -b does not work at all here; I have to use -M indeed in this case. holgerw
update-po: $(SOURCE_FILES)
# Let's keep POT files next to PO files
- $(SPHINX) -M gettext -d $(BUILD_DIR)/en $(SOURCE_DIR) $(SOURCE_DIR)/$(LOCALE_DIR)
+ $(SPHINX) -W -M gettext -d $(BUILD_DIR)/en $(SOURCE_DIR) $(SOURCE_DIR)/$(LOCALE_DIR)
@set -ex; for l in $(filter-out en,$(LANGS)); do \
LC_ALL=C.UTF-8 LANG=C.UTF-8 $(SPHINXINTL) update \
-d $(SOURCE_DIR)/$(LOCALE_DIR) \
Reply to: