docs(15.9): document where themes are published and how to install them - #541
Merged
Merged
Conversation
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.
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.
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.rstgains Obtaining a Theme: the coordinates undermaven.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.rstgains Publishing: version on the Fess line, raise the version whenever the archive changes because a published version is never overwritten, and enumerate versions frommaven-metadata.xmlrather than a directory listing. TheversionandminFessVersionfield descriptions now state the convention, and the manifest example moves off1.0.0/15.7, which contradicted the convention it is meant to illustrate.install/fess-setup.rstdocumentsinstall theme,list themesandremove theme, including whatlist themesdoes 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-setupcommands 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_doctreealone does not report an unresolved`Section`_link, so a run through the full pipeline was added; a deliberately broken reference then shows up asUnknown target name.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.7in the manifest example.Noticed, not changed here
install/fess-setup.rstopens 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.ja,koandzh-cnadmin/theme-guide.rsthave 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.