Integrate clap-markdown in ghciwatch
#248
Conversation
- Add a hidden `--generate-markdown-help` option to generate Markdown docs for the CLI options - Cleaned up the CLI help to include examples and make things render nicer - Added more detail for some options
9999years
force-pushed
the
rebeccat/dux-2313-integrate-cli-documentation
branch
from
c4ea57d
to
5fde9a0
Compare
| @@ -51,7 +52,7 @@ indoc = "1.0.6" | |||
| itertools = "0.11.0" | |||
| line-span = "0.1.5" | |||
| miette = { version = "5.9.0", features = ["fancy"] } | |||
| nix = { version = "0.26.2", default_features = false, features = ["process", "signal"] } | |||
| nix = { version = "0.26.2", default-features = false, features = ["process", "signal"] } | |||
There was a problem hiding this comment.
Got a warning about this, maybe a toolchain update caught it? IDK.
| /// Ghciwatch loads a GHCi session for a Haskell project and reloads it | ||
| /// when source files change. | ||
| /// | ||
| /// ## Examples |
There was a problem hiding this comment.
Adding some examples. This is a sort of weird compromise; these look decent in --help output unprocessed and also render as Markdown.
clap doesn't have any hooks to customize how the docstrings are preprocessed, so we have to turn off preprocessing (or it'll line-wrap the examples). Unfortunately, that loses us all formatting for this text...
| /// Don't reload for `README.md` files: | ||
| /// | ||
| /// ghciwatch --reload-glob '!src/**/README.md' | ||
| #[allow(rustdoc::invalid_rust_codeblocks)] |
There was a problem hiding this comment.
And rustdoc doesn't like that the indented shell examples aren't valid Rust code. (You're supposed to use triple backticks annotated as plain or something for that, but of course we don't want it to show up in the output.)
| author, | ||
| verbatim_doc_comment, | ||
| max_term_width = 100, | ||
| override_usage = "ghciwatch [--command SHELL_COMMAND] [--watch PATH] [OPTIONS ...]" |
There was a problem hiding this comment.
--command and --watch are the really important options so I pulled them out; the default usage string was ghciwatch [OPTIONS] which isn't very useful.
| /// | ||
| /// By default, only changes to `.cabal` or `.ghci` files or Haskell source files being | ||
| /// moved/removed will trigger restarts. | ||
| /// | ||
| /// Due to a `ghci` bug, the `ghci` session must be restarted when Haskell modules are removed | ||
| /// or renamed: https://gitlab.haskell.org/ghc/ghc/-/issues/11596 | ||
| /// Due to [a `ghci` bug][1], the `ghci` session must be restarted when Haskell modules are removed |
There was a problem hiding this comment.
Kinda clumsy to have markdown link syntax in the --help output like this but it looks OK enough and it renders correctly as Markdown.
It'd be nice to have a system that let us do some more advanced templating to add more detail in the manual...
~~Blocked on #248~~ Adds the actual user manual mdBook, but doesn't build or publish it.
Blocked on #247Cleans up
ghciwatch --helpand makes the docstrings render nicely as Markdown in an mdBook.