Skip to content

Покрытие документации общей проверкой и скрипт ссылок на пул-реквест - #17

Merged
keyfire merged 4 commits into
mainfrom
chore/docs-coverage-and-changelog-link
Sep 12, 2026
Merged

keyfire merged 4 commits into
mainfrom
chore/docs-coverage-and-changelog-link

Conversation

@keyfire

@keyfire keyfire commented Sep 12, 2026

Copy link
Copy Markdown
Owner

Two backlog items that are both about the same thing: work the repository was doing by hand and a
neighbour had already automated.

The coverage checks come from the shared guard

check_tools and check_environment each wrote the set difference out in full. The tools copy
guarded against an empty sources side and judged both directions; the environment copy did
neither. That is the gap coverage_problems in docsguard
exists for, and the version here is already pinned at v0.8.0. What stays in the script is what
the sources are and where the pages are.

Turning on the other direction for variables needed one fix first. The reader only saw a variable
asked for by name, and EDT_BRIDGE_LANG and EDT_BRIDGE_PLUGIN_INDEX are read through a constant
bound above:

PLUGIN_INDEX_ENV = "EDT_BRIDGE_PLUGIN_INDEX"
...
os.environ.get(PLUGIN_INDEX_ENV)

So both were invisible to the check, the installation page could have dropped either without a
word, and with phantoms on they would have been reported as documented-but-not-read. A second
pattern, the same shape elemctl uses, makes them visible. It requires the name to fill the quotes
on its own, so set "EDT_BRIDGE_TOKEN=..." in the batch file the auto-start writes is not taken
for a declaration.

What did NOT move: claim_problems. It guards a statement several documents and the code all have
to make in the same words, and its table earns itself after a correction has reached one place and
left the others behind. Nothing here has drifted that way. The one candidate worth checking, the
port the bridge listens on, is spelled 8770 in all thirteen places that name it. The reason is
written down in the module docstring so the next reader does not have to check again.

scripts/changelog-link.py

Every changelog entry ends with a link to its pull request, in both editions, and the number only
exists once the pull request is open. Writing that into CHANGELOG.md and docs/ru/CHANGELOG.ru.md
by hand, at a 100-character wrap, is how one of the two ends up wrong. The script is elemctl's,
adjusted for this repository:

  • the Russian edition is a directory away, in docs/ru/;
  • the rebuild step is node scripts/sync-docs.mjs and nothing else. The command reference is built
    by a second generator that reads --help, and a changelog entry cannot change it;
  • the mirrors here are gitignored, so a stale one cannot turn main red. It can make
    scripts/check_docs.py report a word the source no longer carries, since the guard reads every
    docs/*.ru.md. That is the reason the rebuild still runs and still sets the exit code.

The script is born under both conventions the repository now guards: the process it starts names
its encoding, and the write passes newline="". python/tests/test_conventions.py covers
scripts/, so neither is a promise.

How it was verified

python -m pytest -q is 192 passed, 1 skipped, up from 180: nine tests for the new script and
three more around coverage, including the two directions and a reader that has gone quiet.
python scripts/check_docs.py is green, and the link on the entries below was written by the new
script rather than by hand.

@keyfire
keyfire merged commit b00c8c9 into main Sep 12, 2026
6 checks passed
@keyfire
keyfire deleted the chore/docs-coverage-and-changelog-link branch September 12, 2026 06:49
coverage_problems даёт обе стороны разности и сторожа пустого читателя;
читатель переменных научился видеть имя, записанное в константу, поэтому
страница установки судится и в обратную сторону.
changelog-link.py ставит ссылку в записи верхнего раздела обеих редакций,
переносит её на отдельную строку при полной ширине и пересобирает зеркала.
Ссылка проставлена самим scripts/changelog-link.py - первый живой запуск.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant