jj-vcs
wip: implement `jj docs` command
This is a rudimentary approach to embedding docs in the binary. It uses termimad to render markdown into the terminal. It still needs a lot of work, but something like jj docs FAQ can in fact work right now.
Getting this in a submittable state probably isn't too much work, but polishing the docs so they look good will take a bit of effort.
Closes #1294.
If applicable:
- [ ] I have updated
CHANGELOG.md - [ ] I have updated the documentation (README.md, docs/, demos/)
- [ ] I have updated the config schema (cli/src/config-schema.json)
- [ ] I have added tests to cover my changes
staticfilemap has a disallowed license, unfortunately. So I'll have to find an alternative or fix it another way, it seems.
staticfilemaphas a disallowed license, unfortunately. So I'll have to find an alternative or fix it another way, it seems.
rust-embed is promising and MIT, so I think that will work.
So this is separate from a man page or extended help topics?
That's right. The idea is that the user can just read any of docs/ folder immediately on the command line with nothing extra; I suppose you could call that "Extended help", perhaps. :) Speaking of, I don't know why we don't generate man pages for our releases, either...
Both Git and Breezy have a lot of info accessible as help subcommands. (that's what I call extended help)
This proposal is for a separate command called docs.
Correct. Part of the problem there is that, as Ilya noted in https://github.com/martinvonz/jj/issues/1294, I'm also hesitant to touch help too much, because it's generated by Clap and we would probably need to do some significant restructuring to make it more "open ended" so we can customize it in the ways we want, e.g. allowing unified help and docs all in the same command. It's possible we'll do that, but I think we want to be totally clear on what we're trying to accomplish before executing on it. For example, grouping the commands into sections is something we currently can't do in the help output (limitation of Clap), and there aren't easy solutions to it now, so we want to factor considerations like that in before doing it.
Unifying them would be good, I think, but I don't see a clear and easy way to do that right now and in the long run maybe docs will remain conceptually separate, not a strict reference like help is. So, I do think having this as a separate docs subcommand is the right way to go for the near-to-medium future, at least.
It's possible we'll do that, but I think we want to be totally clear on what we're trying to accomplish before executing on it. For example, grouping the commands into sections is something we currently can't do in the help output (limitation of Clap), and there aren't easy solutions to it now, so we want to factor considerations like that in before doing it.
For the record (though it's not totally relevant to this ticket), I think probably the best way to do this in the really long run would be to move almost all of the command definitions out of .rs files which use #[derive], and into something like YAML files describing the commands in a more easily consumable format. That will give us the ability to write more open ended "code generators" that can for example read the files and allow us to generate 95% of help output programmatically, while giving us more customization for the final bits. Then we could probably unify all these things.