slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc:DOCS

Browse Source
This commit is contained in:
Simon Michael 2025-09-26 10:48:30 -10:00
parent d1138c0f33
commit a345116f29
1 changed files with 42 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
doc/DOCS.md
View File

@ -5,7 +5,7 @@
<!-- toc -->
</div>
## Four kinds of documentation
## hledger's documentation structure
<div style="margin:1em 2em; font-style:italic;">
"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)
</div>
## 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
<!-- keep synced with Justfile, Shake.hs -->
### 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)