diff --git a/doc/DOCS.md b/doc/DOCS.md index 543ab74e3..4a7490d03 100644 --- a/doc/DOCS.md +++ b/doc/DOCS.md @@ -5,7 +5,7 @@ -## Four kinds of documentation +## hledger's documentation structure
"There is a secret that needs to be understood in order to write good @@ -16,8 +16,6 @@ functions, and require four different approaches to their creation." --[Daniele Procida] (https://news.ycombinator.com/item?id=21289832)
-## hledger's documentation structure - 2019: out of date, needs update. Project documentation lives in a number of places: @@ -74,30 +72,37 @@ hledger doc files can be divided into several groups: Last updated: 2025-09 +### Compile the Shake script + +`Shake.hs` automates some doc maintenance tasks (complementing `Justfile)`. +Most contributors don't need to use it, but if you do, compile it like so: +in the hledger repo, run: +``` +$ ./Shake.hs +``` + +### Update options help + +Edit general options definitions in `hledger/Hledger/Cli/CliOptions.hs` +and command options definitions in `hledger/Hledger/Cli/Commands/*.hs`. + ### Update manuals' content -Updates to the manuals' content are welcome and encouraged! +Updates and fixes for the manuals' content are welcome and encouraged! They can be committed together with related code changes, or separately. -Note the manuals have (a) source files and (b) files generated from these by scripts. +The manuals have (a) source files, kept in the hledger repo and (b) generated files derived from those. Don't edit the generated files, such as: - `hledger/hledger.md` or `hledger-ui/hledger-ui.md` in the hledger repo - `site/src/1.50/hledger*.md` or `site/src/dev/hledger*.md` in the hledger_site repo -Instead, edit the source files, in the hledger repo's master branch. Usually that means: +Instead, edit the source files: - `hledger/hledger.m4.md` or `hledger/Hledger/Cli/Commands/*.md` for the hledger manual - `hledger-ui/hledger-ui.m4.md` for the hledger-ui manual - `hledger-web/hledger-web.m4.md` for the hledger-web manual. -If you click "edit this page" on a recent release manual on the website, you'll see all of its source files listed. - -### Compile the Shake script - -`Shake.hs` automates some doc maintenance tasks (complementing `Justfile)`. -If you use it, it's best to compile it first: in the hledger repo, run: -``` -$ ./Shake.hs -``` +(There are a few more source files which change less often; +if you click "edit this page" on a recent release manual on the website, you'll see all source files listed.) ### Update manuals' generated files @@ -109,32 +114,23 @@ In the hledger repo: first, set current year and month for the man pages: $ just mandates ``` +Then update the lists of command line options in the manuals' source files (only as needed, if command line options or option help have changed): +``` +$ stack build && ./Shake cmddocs -c +``` + Then regenerate the text, man, info, and markdown manuals in hledger*/ from their source files: -``` -$ ./Shake manuals -``` - -To also commit the generated files, run it with -c: - ``` $ ./Shake manuals -c ``` -### Update hledger binaries with latest manuals included - -The next build of the hledger executables will embed the latest text, man and info manuals from hledger*/. Eg: - -``` -$ stack build -``` - ### Update dev manuals on the website -When updates to the generated manuals land in the master branch of the hledger repo on github, -the latest (dev) manuals on hledger.org will update automatically. +When updates to manuals' generated files land in the master branch of the hledger repo on github, +the dev manuals on hledger.org will update automatically. -(The website manuals are rendered from `site/src/VERSION/*.md` in the hledger_site repo, +(The manuals on the website are rendered from `site/src/VERSION/*.md` in the hledger_site repo, which are symlinked copies of `hledger/hledger.md`, `hledger-ui/hledger-ui.md` and `hledger-web/hledger-web.md` in the hledger repo.) ### Update release manuals on the website @@ -144,7 +140,8 @@ Contributors can do this, but doing it the right way is a little complicated; yo The release manuals on the website are rendered from `site/src/1.50/*.md`, `site/src/1.43/*.md`, etc. These are generated as follows: -In the hledger repo, with the hledger_site repo symlinked as `./site`, for each major release REL that needs updating: +In the hledger repo, with the hledger_site repo symlinked as `./site`;\ +for each major release REL that needs updating: 1. Cherry pick the manuals' content updates for REL (not generated files updates) from `master` to `REL-branch` 2. In master, run `just site-manuals-snapshot REL` to update the release manuals in the site repo. @@ -152,6 +149,18 @@ In the hledger repo, with the hledger_site repo symlinked as `./site`, for each When these commits land in the hledger_site repo on github, the release manuals on hledger.org will update automatically. +### Update hledger binaries with latest docs + +This ensures the hledger dev executables are embedding the latest manuals' generated files, affecting: +- options help displayed by `--help` +- command docs displayed by `CMD --help` +- manuals displayed by `help`, `--info`, and `--man`. + +Update the options help, manuals' content and manuals' generated files as above, then rebuild: +``` +$ stack build +``` + ## 201901 docs reorg (#920, WIP)