cache-dependency-path:'Doc/requirements.txt'

-name:'Install build dependencies'

run:make -C Doc/ venv

-name:'Build HTML documentation'

run:make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html

-name:'Get list of changed files'

if:github.event_name == 'pull_request'

id:changed_files

uses:Ana06/get-changed-files@v2.2.0

with:

filter:"Doc/**"

format:csv# works for paths with spaces

-name:'Build changed files in nit-picky mode'

if:github.event_name == 'pull_request'

-name:'Build HTML documentation'

continue-on-error:true

run:|

-name:'Build known-good files in nit-picky mode'

-name:'Check warnings'

if:github.event_name == 'pull_request'

run:|

build_doc_oldest_supported_sphinx:

# All RST files under Doc/ -- except these -- must pass Sphinx nit-picky mode,

# as tested on the CI via touch-clean-files.py in doc.yml.

# Add blank lines between files and keep them sorted lexicographically

# to help avoid merge conflicts.

# as tested on the CI via check-warnings.py in reusable-docs.yml.

# Keep lines sorted lexicographically to help avoid merge conflicts.

Doc/c-api/arg.rst

Doc/c-api/datetime.rst

Doc/c-api/descriptor.rst

Doc/c-api/dict.rst

Doc/c-api/exceptions.rst

Doc/c-api/file.rst

Doc/c-api/float.rst

Doc/c-api/gcsupport.rst

Doc/c-api/import.rst

Doc/c-api/init.rst

Doc/c-api/init_config.rst

Doc/c-api/intro.rst

Doc/library/calendar.rst

Doc/library/cgi.rst

Doc/library/chunk.rst

Doc/library/cmath.rst

Doc/library/cmd.rst

Doc/library/codecs.rst

Doc/library/collections.abc.rst

EXCLUDE_FILES= {

"Doc/whatsnew/changelog.rst",

}

EXCLUDE_SUBDIRS= {

".env",

".venv",

"env",

"includes",

"venv",

}

PATTERN=re.compile(r"(?P<file>[^:]+):(?P<line>\d+): WARNING: (?P<msg>.+)")

defcheck_and_annotate(warnings:list[str],files_to_check:str)->None:

files_to_check=next(csv.reader([files_to_check]))

forwarninginwarnings:

ifany(filenameinwarningforfilenameinfiles_to_check):

ifmatch:=PATTERN.fullmatch(warning):

print("::warning file={file},line={line}::{msg}".format_map(match))

deffail_if_regression(

warnings:list[str],files_with_expected_nits:set[str],files_with_nits:set[str]

)->int:

all_rst= {

str(rst)

forrstinPath("Doc/").rglob("*.rst")

ifrst.parts[1]notinEXCLUDE_SUBDIRS

}

problem_files=sorted(should_be_clean&files_with_nits)

ifproblem_files:

print("\nError: must not contain warnings:\n")

forfilenameinproblem_files:

print(filename)

forwarninginwarnings:

iffilenameinwarning:

ifmatch:=PATTERN.fullmatch(warning):

print(" {line}: {msg}".format_map(match))

deffail_if_improved(

files_with_expected_nits:set[str],files_with_nits:set[str]

)->int:

iffiles_with_no_nits:

print("\nCongratulations! You improved:\n")

forfilenameinsorted(files_with_no_nits):

print(filename)

print("\nPlease remove from Doc/tools/.nitignore\n")

defmain()->int:

parser=argparse.ArgumentParser()

parser.add_argument(

"--check-and-annotate",

"and annotate those with warnings on GitHub Actions",

)

parser.add_argument(

"--fail-if-regression",

action="store_true",

help="Fail if known-good files have warnings",

)

parser.add_argument(

"--fail-if-improved",

action="store_true",

help="Fail if new files with no nits are found",

)

args=parser.parse_args()

assertPath("Doc").exists()andPath("Doc").is_dir(),wrong_directory_msg

withPath("Doc/sphinx-warnings.txt").open()asf:

warnings=f.read().splitlines()

cwd=str(Path.cwd())+os.path.sep

files_with_nits= {

warning.removeprefix(cwd).split(":")[0]

}

withPath("Doc/tools/.nitignore").open()asclean_files:

files_with_expected_nits= {

filename.strip()

iffilename.strip()andnotfilename.startswith("#")

}

ifargs.check_and_annotate:

check_and_annotate(warnings,args.check_and_annotate)

ifargs.fail_if_regression:

exit_code+=fail_if_regression(

warnings,files_with_expected_nits,files_with_nits

)

ifargs.fail_if_improved:

exit_code+=fail_if_improved(files_with_expected_nits,files_with_nits)

if__name__=="__main__":

sys.exit(main())