diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f676959ca0..37b991e080 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -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 diff --git a/Documentation/Makefile b/Documentation/Makefile index a04da672c6..a3868a462f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -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:: diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh new file mode 100755 index 0000000000..92cfc0a15a --- /dev/null +++ b/Documentation/lint-manpages.sh @@ -0,0 +1,108 @@ +#!/bin/sh + +extract_variable () { + ( + cat ../Makefile + cat </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 diff --git a/Makefile b/Makefile index f25b2e80a1..80ff67bad6 100644 --- a/Makefile +++ b/Makefile @@ -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 # diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh index de41888430..02b3af3941 100755 --- a/ci/test-documentation.sh +++ b/ci/test-documentation.sh @@ -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" }