Skip to content

docs(15.9): document where themes are published and how to install them - #541

Merged
marevol merged 1 commit into
mainfrom
docs/theme-distribution
Sep 20, 2026
Merged

marevol merged 1 commit into
mainfrom
docs/theme-distribution

Conversation

@marevol

@marevol marevol commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

Why

Nothing in the documentation said where to get a static theme. The admin guide described the upload form, the development guide described building one, and neither named the repository the project publishes them to — which until now had nothing in it. Themes are now published, so the gap is worth closing.

What changes

Three pages per language, 15.9 only (the development tree).

admin/theme-guide.rst gains Obtaining a Theme: the coordinates under maven.codelibs.org/release/org/codelibs/fess/themes/, the rule that a theme's version is the Fess line it targets, and the two ways to install one — bin/fess-setup install theme <name>, or download and upload on that page.

dev/theme-development.rst gains Publishing: version on the Fess line, raise the version whenever the archive changes because a published version is never overwritten, and enumerate versions from maven-metadata.xml rather than a directory listing. The version and minFessVersion field descriptions now state the convention, and the manifest example moves off 1.0.0 / 15.7, which contradicted the convention it is meant to illustrate.

install/fess-setup.rst documents install theme, list themes and remove theme, including what list themes does when the directory index it reads has not been generated yet.

Both the theme guide and the development guide explain why there is no upper-bound field: a published archive never changes, so a bound could not be added later for a theme that stops working on a newer Fess. Not publishing it for that line says the same thing, at the point it is known.

Depends on

The fess-setup commands are codelibs/fess#3461. The rest of the text describes what is already published.

Verification

Every changed file was parsed with docutils and compared against the same file on main, so only newly introduced problems are reported — the translated theme guides already carry short heading rules, which would otherwise bury a real mistake. All 21 files: no new messages, no change in section structure, no inline markup left unparsed.

Two properties were checked by breaking them on purpose rather than assumed:

  • publish_doctree alone does not report an unresolved `Section`_ link, so a run through the full pipeline was added; a deliberately broken reference then shows up as Unknown target name.
  • docutils measures a heading rule in columns, so CJK rules are generated from display width rather than counted.

Parity across the seven languages was checked mechanically: each gains the same three command blocks, the same repository URL in both pages, the same two cross-references, and none still shows 1.0.0 / 15.7 in the manifest example.

Noticed, not changed here

  • install/fess-setup.rst opens with "included with the |Fess| ZIP package". Since build: ship bin/fess-setup in the rpm and the deb, not only the zip fess#3431 the launcher and its jar ship in the RPM and DEB packages too, so that sentence is now wrong in all seven languages — a separate fix.
  • The ja, ko and zh-cn admin/theme-guide.rst have heading rules shorter than their titles' display width, and docutils warns on almost every heading. It predates this branch and affects headings this PR does not add.

Nothing said where to get a static theme. The admin guide described the
upload form, the development guide described building one, and neither
named the repository the project publishes them to -- which until now
had nothing in it.

The theme guide gains a section on obtaining a theme: the coordinates,
the rule that a theme's version is the Fess line it targets, and the two
ways to install one. The development guide gains the publishing half of
that rule -- version on the Fess line, raise it whenever the archive
changes, and enumerate versions from maven-metadata.xml rather than a
directory listing, which is generated on a schedule.

Both pages explain why there is no upper-bound field: a published
archive never changes, so a bound could not be added later for a theme
that stops working on a newer Fess. Not publishing it for that line says
the same thing, at the point it is known.

The manifest example moves off 1.0.0 / 15.7, which contradicted the
convention it is meant to illustrate.

The fess-setup page documents install theme, list themes and remove
theme, including what list themes does when the directory index it reads
is not there yet.
@marevol marevol self-assigned this Sep 20, 2026
@marevol
marevol merged commit 9ab5d0b into main Sep 20, 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