FODS documentation

[thielema]

some extensions to documentation regarding FODS export

How can I regenerate hledger.txt? just only lists targets for Haddock generation.
Why is it checked into the Repo, since it seems to be generated?

[simonmichael]

Most of the heavy doc building is in Shake.hs.

1. ./Shake.hs to compile that
2. ./Shake to see targets
3. ./Shake cmddocs to update the .txt files, which are used in hledger's --help output
4. ./Shake manuals to update the other manual formats, which are embedded as hledger help / hledger-ui --help / hledger-web --help

[simonmichael]

I guess they're checked in because

• They are needed to build hledger. Generating them automatically as part of the build sounds a bit difficult and likely to be fragile.
• It's useful to be able to review the changes with git, for troubleshooting and awareness.

[simonmichael]

• they (or at least the man and info manuals) are artifacts needed by packagers.

[thielema]

I have run those Shake commands. It is difficult to prevent stack from downloading its own versions of GHC. I have installed them already globally. I use the --system-ghc option of stack, but stack seems to be called in other scripts, too.
Now I get many changes to many doc files. I better omit those in my commits. Maybe it is easier you run the documentation update scripts?

[simonmichael]

I have run those Shake commands. It is difficult to prevent `stack` from downloading its own versions of GHC.

If you install stack with ghcup these days, it offers to configure it to use the ghcup-managed system ghc. These are the settings you need in ~/.stack/config.yaml: system-ghc: true install-ghc: false Running stack scripts like Shake.hs might still download a lot of deps, if they use a snapshot different from what you've been using; to avoid this I try to keep all such scripts using the default dev snapshot (whatever is currently configured in stack.yaml).

Now I get many changes to many doc files. I better omit those in my commits. Maybe it is easier you run the documentation update scripts?

The generated docs are sensitive to versions of the (many) docs tools. Yes it's probably easiest to leave [generated] doc updating to me for now. To reduce commit noise, I don't do it with every change to doc source; just every so often (and of course, before release).