Skip to content

docs: generate config/properties.rst from fess_config.properties - #533

Merged
marevol merged 3 commits into
mainfrom
docs/generate-properties-page
Sep 10, 2026
Merged

docs: generate config/properties.rst from fess_config.properties#533
marevol merged 3 commits into
mainfrom
docs/generate-properties-page

Conversation

@marevol

@marevol marevol commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

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.properties automatically. Merge or close #532 either way; this
replaces the file wholesale.

What was wrong

config/properties.rst was maintained by hand. Measured against fess_config.properties:

  • 120 keys missing — the whole api.* family, app.cipher.algorithm, and more.
  • 10 keys that no longer exist, several under a misspelling: 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.tile had even acquired a description invented
    to match the typo: "The domain name of the tile server."

And it was English-only and orphaned: all seven config/index.rst hold the same 39
entries 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.html returns 200 while the Japanese path
returns 404. It has been carried forward by create_version.sh since 14.17.

What this does

Generates the tables from fess_config.properties, so the page cannot drift from the
configuration it documents, and adds the page to all seven languages.

file owns
fess_config.properties (fess repo) keys, defaults, English descriptions, headings, order
<lang>/15.9/config/properties.po translations, per language and per version
<lang>/15.9/config/properties.rst generated between the GENERATED markers; the title and intro are outside them and stay editable

tools/gen_properties_doc.py follows tools/update_eol.py: same marker convention, same
--check mode, a sibling test file, standard library only. It carries a minimal .po
reader because Python's gettext reads compiled .mo, not .po — real gettext format,
so Poedit, Weblate and msgfmt --check all work on the catalogues.

tools/update_properties_doc.sh is run by hand against a fess checkout. Nothing is
vendored here.

What CI can and cannot check

fess_config.properties is not copied into this repository, so --check cannot
compare a page against fess. Divergence there surfaces when someone runs the script; the
generated block says so and names it.

What --check does verify, offline, is that the pages have not drifted from each other or
from their catalogues. Exercised against four kinds of tampering, each caught with exit 1:

tampering what --check says
a description edited in place in ja '…' is neither the English text nor a translation in ja/15.9/config/properties.po
a default value changed in ja keys, defaults or table layout differ from en -- regenerate with tools/update_properties_doc.sh
a table row deleted from ja same
the GENERATED-END marker removed no GENERATED-BEGIN/END markers in the page

Translation

The catalogues ship with every msgstr empty, so all seven languages start in English and
gain their translation as a catalogue is filled. English gets no catalogue — it is what
fess_config.properties already holds.

Verified end to end by translating three entries into Japanese and regenerating: the
section heading, the table caption and the description all switched, --check stayed
green, 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.sh carries them into
a 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 existing
    update_eol suite unaffected).
  • tools/gen_properties_doc.py --check — the 7 pages agree.
  • tools/update_eol.py --check — unaffected.
  • tools/check_headings.py on all seven 15.9 trees — clean.
  • Every generated block parsed with docutils — 0 warnings in all seven languages,
    including the translated Japanese variant. Descriptions carrying Access-Control-* and
    api.cors.* are escaped, so they no longer risk tripping inline-markup recognition.
  • Regenerating twice is a no-op (no change).
  • The English page goes from 529 keys to 639: 120 added, 10 stale removed.

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.

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.
@marevol marevol self-assigned this Sep 10, 2026
@marevol
marevol merged commit 1ec28c9 into main Sep 10, 2026
2 checks passed
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