docs: generate config/properties.rst from fess_config.properties - #533
Merged
Conversation
The configuration reference page was maintained by hand and had rotted.
Measured against fess_config.properties it was 120 keys short, and it
documented 10 keys that no longer exist -- several under a misspelling,
one of which (domain.tile) had acquired an invented description, "The
domain name of the tile server". It also existed only in English, and in
none of the seven config/index.rst toctrees, so it was published but
unreachable from navigation.
Generate the rows instead, and let a person write only the prose around
them.
fess_config.properties the keys, defaults, English descriptions,
headings and order. Edit there.
<lang>/.../properties.po the translations, per language and per
version. Edit these.
<lang>/.../properties.rst generated between the GENERATED markers.
tools/gen_properties_doc.py reads the properties file, merges a gettext
catalogue, and rewrites the block, in the shape tools/update_eol.py
already established. It needs a fess checkout, so it is driven by
tools/update_properties_doc.sh and run by hand; nothing is vendored here.
That means --check cannot compare a page against fess. What it does
verify, offline and in CI, is that the seven pages still agree with each
other on keys, defaults and table layout, and that every string differing
from English is backed by a msgstr. That catches a page edited by hand,
which is the failure this replaces.
The page now exists in all seven languages and is in all seven toctrees.
The catalogues ship with every msgstr empty, so every language starts in
English and gains its translation as the catalogue is filled. Because the
catalogues live inside the version tree, create_version.sh carries them
forward with its existing cp -r.
codelibs/fess#3435 removes four keys whose value had no effect: three theme keys with no caller at all, and rag.chat.message.max.length, which is read as a system property and was the only one of the 44 keys read that way also declared in fess_config.properties. Regenerated: 639 rows to 635. rag-chat.rst described that key as "read as a System Property; the entry in fess_config.properties is not used". The second half is now moot, so it goes -- in all seven languages. Where to set it is unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requires codelibs/fess#3434, which adds the group-heading marker this reads, and
codelibs/fess#3435, which drops four keys whose value had no effect — the pages here are
generated against both, so they show 635 keys rather than 639. Merge those first. Supersedes
#532 — that PR hand-fixed the jcifs names on this page; the generated page picks them up
from
fess_config.propertiesautomatically. Merge or close #532 either way; thisreplaces the file wholesale.
What was wrong
config/properties.rstwas maintained by hand. Measured againstfess_config.properties:api.*family,app.cipher.algorithm, and more.app.cipher.algorism,app.digest.algorism,domain.tile,http.proxy.Host,app.encrypt.key,cookie.default.expires,crawler.document.alphanum.term.size,online.help.name.esreq,query.gsa.index.field.content_type,app.encrypt.property.patterns.domain.tilehad even acquired a description inventedto match the typo: "The domain name of the tile server."
And it was English-only and orphaned: all seven
config/index.rsthold the same 39entries and this page is in none of them. Sphinx builds documents outside the toctree, so
it was published but unreachable from navigation —
fess.codelibs.org/15.8/config/properties.htmlreturns 200 while the Japanese pathreturns 404. It has been carried forward by
create_version.shsince 14.17.What this does
Generates the tables from
fess_config.properties, so the page cannot drift from theconfiguration it documents, and adds the page to all seven languages.
fess_config.properties(fess repo)<lang>/15.9/config/properties.po<lang>/15.9/config/properties.rstGENERATEDmarkers; the title and intro are outside them and stay editabletools/gen_properties_doc.pyfollowstools/update_eol.py: same marker convention, same--checkmode, a sibling test file, standard library only. It carries a minimal.poreader because Python's
gettextreads compiled.mo, not.po— real gettext format,so Poedit, Weblate and
msgfmt --checkall work on the catalogues.tools/update_properties_doc.shis run by hand against a fess checkout. Nothing isvendored here.
What CI can and cannot check
fess_config.propertiesis not copied into this repository, so--checkcannotcompare a page against fess. Divergence there surfaces when someone runs the script; the
generated block says so and names it.
What
--checkdoes verify, offline, is that the pages have not drifted from each other orfrom their catalogues. Exercised against four kinds of tampering, each caught with exit 1:
--checksaysja'…' is neither the English text nor a translation in ja/15.9/config/properties.pojakeys, defaults or table layout differ from en -- regenerate with tools/update_properties_doc.shjaGENERATED-ENDmarker removedno GENERATED-BEGIN/END markers in the pageTranslation
The catalogues ship with every
msgstrempty, so all seven languages start in English andgain their translation as a catalogue is filled. English gets no catalogue — it is what
fess_config.propertiesalready holds.Verified end to end by translating three entries into Japanese and regenerating: the
section heading, the table caption and the description all switched,
--checkstayedgreen, and the CJK section underline came out at the right width because it is generated
from display columns rather than character count (docutils measures a title in columns, so
a character-counted underline is too short and the section is silently dropped). Reverted
before committing so the catalogues ship empty as designed.
Because the catalogues live inside the version tree,
create_version.shcarries them intoa new version with its existing
cp -r— no change to that script.Verification
python -m unittest discover -s tools— 79 tests, 0 failures (55 new, plus the existingupdate_eolsuite unaffected).tools/gen_properties_doc.py --check— the 7 pages agree.tools/update_eol.py --check— unaffected.tools/check_headings.pyon all seven 15.9 trees — clean.including the translated Japanese variant. Descriptions carrying
Access-Control-*andapi.cors.*are escaped, so they no longer risk tripping inline-markup recognition.no change).Size
25 files, roughly +28,000 lines: 7 pages of 639 rows each and 6 catalogues. The bulk is
generated and regenerable from one command.