cyclopts
cyclopts copied to clipboard
BrianPugh
[feature request]: automatic markdown documentation generation
A pretty useful feature Typer has is automatic documentation generation. It's really helpful to have this as part of pre-commit hooks and in the CI pipeline.
I wonder if cyclopts could also have this?
I think we can do that! I think a limitation is that the output docs format will have to be the same format as App.help_format. I'll try and get to this!
@BrianPugh This feature would be very useful to us as we're building out a new CLI app. Were you able to chip away at this?
I haven't started this effort yet; I'll begin it after I finish up my dictionary-support efforts.
Hey @BrianPugh, do you need help with this? I would really like to switch to Cyclopts in my projects, this is the only thing holding me back. Let me know if I could do anything.
Thanks for offering! I'm in the middle of a big refactor that should make this feature pretty easy for a v3.0.0 cyclopts. Still targeting about a month away.
I've been looking at for the capability too to switch away from typer entirely. Current we use https://github.com/bruce-szalwinski/mkdocs-typer for the doc's gen rather than typer's own, I would if a similar plugin would be possible.
this hasn't fallen of my radar; I'm just currently prioritizing getting CLI completions out, then I can work on this!
hey @danielgafni!
Now that v3 is out and pretty stable, I would love help on this feature. Basically now the entire command-tree and parameter naming is pre-computed (for a given command) and this would be much easier now to implement (but still with it's nuances). If you could help out producing this feature, I would be glad to contribute to the feature branch and answer questions/give advice when needed. Anytime thats not fixing bugs/docs I currently feel compelled to work on shell autocompletion, which I'm not finding to be a very fun task (I'm not particularly familiar with bash/zsh/fish autocompletion scripts).
I would say just start hacking away at it, and I can give course correction (either through comments or through direct commits) along the way!
Hello all,
This is a feature that would help me out a ton too; I've made a crude doc generator that I use for my other projects.
The Fork is here: https://github.com/ESPR3SS0/cyclopts
I say crude because it relies on using inspect to pull from the function signatures, and is fairly limited compared to the output from --help. I image a true implementation would lean on some of the parsing logic already in the repo...
With that in mind, I'd enjoy hacking away at a true implementation @BrianPugh . Let me know if I should ditch inspect, or if there's any direction you think the implementation should go.
For example the program:
from cyclopts import App
from cyclopts.doc_gen import init_docs, generate_docs
from enum import Enum
app = App()
class MyType(Enum):
OPT1 = "opt1"
OPT2 = "opt2"
OPT3 = "opt3"
@app.command()
def hello(inp: str, extra: MyType, last: str | None ="Nop"):
"""Hello command.
This command will say hello to you :D
"""
print(f"Hello {inp} {last} type was: {extra}")
@app.command()
def shell():
"""Enter shell.
This command will enter a shell for you :D.
"""
app.interactive_shell(prompt='MyShell>')
app = init_docs(app)
app()
Will result in docs:
## ``tmp.py``
**Usage:**
``$ tmp.py [OPTIONS] COMMAND [ARGS]...``
**Options:**
* ``--help``: Show help and exit.
* ``-h``: Show help and exit.
* ``--version``: Show version and exit.
**Commands:**
* ``hello``: Hello command.
* ``shell``: Enter shell.
* ``docs``: Generate Markdown documentation for this CLI.
## ``tmp.py hello``
Hello command.
This command will say hello to you :D
**Usage:**
``$ tmp.py hello [OPTIONS] INP EXTRA``
**Arguments:**
* ``INP``: Positional argument (str).
* ``EXTRA``: Positional argument (MyType).
**Options:**
* ``--last``: str | None [default: Nop]
## ``tmp.py shell``
Enter shell.
This command will enter a shell for you :D.
**Usage:**
``$ tmp.py shell ``
## ``tmp.py docs``
**Usage:**
``$ tmp.py docs [OPTIONS]``
**Options:**
* ``--output``: Path | None [default: None]
Hey @ESPR3SS0 ! Thanks for the PoC!
I imagine that the "real" implementation would probably have to iterate over the app and consume the output of the private App._assemble_help_panels. However, I haven't deeply thought about it.
My main current hesitation is that there are open issues (#346, #421, #442) that want greater configuration/customization around the help page, so we want to make sure we don't code ourselves into a corner here.
I would definitely love a PR and would be more than happy to help (with both implementation, as well as just discussion/answering questions)!
v4 beta is out now! Please give it a try and report back and success/issues. I'll let this sit for a week; if feedback is mostly positive I'll perform the full release.
- Changelog: https://github.com/BrianPugh/cyclopts/releases/tag/v4.0.0b1
- Documentation: https://cyclopts.readthedocs.io/en/latest/
- Install it via:
pip install cyclopts==4.0.0b1
Thanks Brian, I happen to be building a new project that needs a CLI, I'll throw Cyclopts in to test this new feature!
Very impressed so far, I think you did an amazing job with the project.
Forgot to report here but everything worked well for me! Thanks a lot!
I was only wishing for an mkdocs generator.
- I assume the new APIs should make it easier to make user-defined generators?
- As I understand you'r using Sphinx and likely aren't interested in implementing Mkdocs yourself, is this assumption correct?
Just found something that could be improved: the docs for each argument should specify the environment variable (coming from cyclopts.config.Env) that can be used to set it. Probably same for yaml/toml/etc config keys.
Or maybe there could be a separate docs section for each config type.