add doc:links and docs:links:check

[Jannis-Mittenzwei]

closes #409

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)
B Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[ArBridgeman]

Suggested change

	* #409: Doc link & checks
	* #409: Added nox tasks for `doc:links` and `docs:links:check`

[ArBridgeman]

1. At the top of the docs/changes/unreleased.md, please add to the ## Summary section. Below is some suggested text.
2. Please modify the suggested to explain why you selected certain values & what they do.
3. Please, above the Sonar part, add ### Sonar.

Links in Documentation

This version of the PTB adds nox tasks to check links present in our documentation:

• docs:link - List all the links within the documentation
• docs:links:check - Checks whether all links in the documentation are accessible

docs:links:check is run in the CI checks.yml. If this step fails in the CI, please check the output & manually resolve the issues. There might be some cases where you need to update your doc/conf.py with specific values for the allowed options for the Linkcheck Builder.

We recommend the following values be added

linkcheck_rate_limit_timeout = 40
linkcheck_timeout = 5
linkcheck_delay = 20
linkcheck_retries = 2
linkcheck_anchors = False
linkcheck_ignore: list[str] = []
linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to
    # the canonical URI will be treated as "working".
    r"https://github\.com/.*": r"https://github\.com/login*"
}

[ArBridgeman]

The repository has moved; thus, the reference text should be updated to reflect that.

Suggested change

	The `sphinx-multiversion` extension is a modified copy of `Holzhaus/sphinx-multiversion <https://github.com/sphinx-contrib/multiversion>`_. This copy was taken from version :code:`0.24.0`.
	The `sphinx-multiversion` extension is a modified copy of `sphinx-contrib/multiversion <https://github.com/sphinx-contrib/multiversion>`_. This copy was taken from version :code:`0.24.0`.

[ArBridgeman]

Please update project-template/{{cookiecutter.repo_name}}/doc/conf.py with values that you think are worthwhile to have.

[ArBridgeman]

Suggested change

	prog="nox -s release:prepare",
	prog="nox -s docs:links:check",

[ArBridgeman]

Suggested change

	usage="nox -s release:prepare -- [-h] [-o |--output]",
	usage="nox -s docs:link:check -- [-h] [-o |--output]",

[ArBridgeman]

unused import

Suggested change

import requests # type: ignore

[ArBridgeman]

unused import

Suggested change

from itertools import repeat

[ArBridgeman]

Container & Iterable are unused imports. Please remove.

Suggested change

from collections.abc import (

[ArBridgeman]

unused import

Suggested change

import re

[ArBridgeman]

unused import

Suggested change

import os

[ArBridgeman]

remove print here?

Suggested change

print(sp.returncode)

[ArBridgeman]

You should be able to create an integration test and/or unit test(s) similar to https://github.com/exasol/python-toolbox/blob/main/test/unit/util/dependencies/poetry_dependencies_test.py.

For the integration test:

• Within a tmp directory, make a simple set up with 1 to 3 links & test that what you capture on the capsys matches what you would expect.

For unit test(s):

• You could either run it over docs_list_links and mock the session like is done https://github.com/exasol/python-toolbox/blob/main/test/unit/nox/_artifacts_test.py or extract your for loop (line 124-136) & test it with hard-coded input like you would expect from the preceding lines.

It is true that we should not test everything that sphinx-build linkcheck does, but as we are building a small part of code (line 124-136) around it, it is best to ensure that the given certain input that we get an expected output. In the example test code (poetry_dependencies_test.py.) above, this was necessitated as when we moved from poetry 1.x to poetry 2.x the format of the pyproject.toml changed, but we had only hard-coded tests that represented a format that no longer existed. An analogous situation could be when we updated sphinx-build that we find the the JSONL format has changed or that the conf.py variable names have changed.

[ArBridgeman]

(In the example with poetry, there was no CI indication before that the code was failing. I just happened to see that the output in the GitHub summary wasn't correct. 😬 . Better to do light testing & catch it earlier on. Tests are relatively free. Developers finding issues isn't as much; we cost more per hour 😉 )

[ArBridgeman]

Suggested change

	"-o", "--output", type=Path, help="path to output file", default=None
	"-o", "--output", type=Path, help="path to copy the output json file", default=None

[ArBridgeman]

maybe something like this
-> separate errors visually with a character like -
-> use a walrus operator in some way so that not doing read_text() twice. If you use a walrus operator then, it should be the first item in the or condition, as otherwise, it may not be set later.

Suggested change

	if sp.returncode == 1 or result_txt.read_text() != "":
	if errors:=result_txt.read_text().splitlines() or sp.returncode == 1:
	escape_red = "\033[31m"
	print(escape_rot + "errors:")
	print('\n'.join(f"- {item}" for item in errors))
	session.error(1)