Merge branch 'ps/check-docs-fix'

"make check-docs" noticed problems and reported to its output but
failed to signal its findings with its exit status, which has been
corrected.

* ps/check-docs-fix:
  ci/test-documentation: work around SyntaxWarning in Python 3.12
  gitlab-ci: add job to run `make check-docs`
  Documentation/lint-manpages: bubble up errors
  Makefile: extract script to lint missing/extraneous manpages
This commit is contained in:
Junio C Hamano 2024-06-17 15:55:54 -07:00
commit dfd668fa84
5 changed files with 122 additions and 36 deletions

View file

@ -122,3 +122,12 @@ check-whitespace:
- ./ci/check-whitespace.sh "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA"
rules:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'
documentation:
image: ubuntu:latest
variables:
jobname: Documentation
before_script:
- ./ci/install-dependencies.sh
script:
- ./ci/test-documentation.sh

View file

@ -485,12 +485,16 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
lint-docs-manpages:
$(QUIET_GEN)./lint-manpages.sh
## Lint: list of targets above
.PHONY: lint-docs
lint-docs: lint-docs-fsck-msgids
lint-docs: lint-docs-gitlink
lint-docs: lint-docs-man-end-blurb
lint-docs: lint-docs-man-section-order
lint-docs: lint-docs-manpages
ifeq ($(wildcard po/Makefile),po/Makefile)
doc-l10n install-l10n::

108
Documentation/lint-manpages.sh Executable file
View file

@ -0,0 +1,108 @@
#!/bin/sh
extract_variable () {
(
cat ../Makefile
cat <<EOF
print_variable:
@\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
EOF
) |
make -C .. -f - print_variable 2>/dev/null |
sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
}
check_missing_docs () (
ret=0
for v in $ALL_COMMANDS
do
case "$v" in
git-merge-octopus) continue;;
git-merge-ours) continue;;
git-merge-recursive) continue;;
git-merge-resolve) continue;;
git-merge-subtree) continue;;
git-fsck-objects) continue;;
git-init-db) continue;;
git-remote-*) continue;;
git-stage) continue;;
git-legacy-*) continue;;
git-?*--?* ) continue ;;
esac
if ! test -f "$v.txt"
then
echo "no doc: $v"
ret=1
fi
if ! sed -e '1,/^### command list/d' -e '/^#/d' ../command-list.txt |
grep -q "^$v[ ]"
then
case "$v" in
git)
;;
*)
echo "no link: $v"
ret=1
;;
esac
fi
done
exit $ret
)
check_extraneous_docs () {
(
sed -e '1,/^### command list/d' \
-e '/^#/d' \
-e '/guide$/d' \
-e '/interfaces$/d' \
-e 's/[ ].*//' \
-e 's/^/listed /' ../command-list.txt
make print-man1 |
grep '\.txt$' |
sed -e 's|^|documented |' \
-e 's/\.txt//'
) | (
all_commands="$(printf "%s " "$ALL_COMMANDS" "$BUILT_INS" "$EXCLUDED_PROGRAMS" | tr '\n' ' ')"
ret=0
while read how cmd
do
case " $all_commands " in
*" $cmd "*) ;;
*)
echo "removed but $how: $cmd"
ret=1;;
esac
done
exit $ret
)
}
BUILT_INS="$(extract_variable BUILT_INS)"
ALL_COMMANDS="$(extract_variable ALL_COMMANDS)"
EXCLUDED_PROGRAMS="$(extract_variable EXCLUDED_PROGRAMS)"
findings=$(
if ! check_missing_docs
then
ret=1
fi
if ! check_extraneous_docs
then
ret=1
fi
exit $ret
)
ret=$?
printf "%s" "$findings" | sort
exit $ret

View file

@ -3759,42 +3759,6 @@ ALL_COMMANDS += scalar
.PHONY: check-docs
check-docs::
$(MAKE) -C Documentation lint-docs
@(for v in $(patsubst %$X,%,$(ALL_COMMANDS)); \
do \
case "$$v" in \
git-merge-octopus | git-merge-ours | git-merge-recursive | \
git-merge-resolve | git-merge-subtree | \
git-fsck-objects | git-init-db | \
git-remote-* | git-stage | git-legacy-* | \
git-?*--?* ) continue ;; \
esac ; \
test -f "Documentation/$$v.txt" || \
echo "no doc: $$v"; \
sed -e '1,/^### command list/d' -e '/^#/d' command-list.txt | \
grep -q "^$$v[ ]" || \
case "$$v" in \
git) ;; \
*) echo "no link: $$v";; \
esac ; \
done; \
( \
sed -e '1,/^### command list/d' \
-e '/^#/d' \
-e '/guide$$/d' \
-e '/interfaces$$/d' \
-e 's/[ ].*//' \
-e 's/^/listed /' command-list.txt; \
$(MAKE) -C Documentation print-man1 | \
grep '\.txt$$' | \
sed -e 's|^|documented |' \
-e 's/\.txt//'; \
) | while read how cmd; \
do \
case " $(patsubst %$X,%,$(ALL_COMMANDS) $(BUILT_INS) $(EXCLUDED_PROGRAMS)) " in \
*" $$cmd "*) ;; \
*) echo "removed but $$how: $$cmd" ;; \
esac; \
done ) | sort
### Make sure built-ins do not have dups and listed in git.c
#

View file

@ -11,6 +11,7 @@ filter_log () {
-e '/^ \* new asciidoc flags$/d' \
-e '/stripped namespace before processing/d' \
-e '/Attributed.*IDs for element/d' \
-e '/SyntaxWarning: invalid escape sequence/d' \
"$1"
}