undefined | Better HN

0 pointsjdxcode2y ago0 comments

it's not complete, but I've been thinking about this problem for years and have been thinking about how to solve it.

I am working on it here: https://github.com/jdx/usage

It's mostly just a README right now, and I'm still iterating on it, talking to friends, but I think I'm getting close. It's definitely not yet written for the average developer to consume yet either. My hope is within the next month or two I might have a usable alpha release of it. I have a use-case for it now so I think it’s finally ready to happen.

If you have any thoughts on my design lmk.

0 comments

6 comments · 4 top-level

cb3212y ago· 2 in thread

You probably already know, but just in case you don't, you might read about http://docopt.org/ It seems to me a lot of your usage ideas could be refinements of / tooling around docopt-style interfaces.

jdxcodeOP2y ago

Yeah I investigated. I don’t think it works well that direction. It is appealing and you can see some elements of it in my current design, though that’s a particular part I’m still unsure of.

It gets way too complicated real quick and a lot of things you _dont_ want to expose in documentation. It’s better to generate docs from a spec than the other way around, I’m pretty sure of this now.

cb3212y ago

There is also generating the whole thing from a function signature (e.g. https://github.com/c-blake/cligen ) since then CLauthors need not learn a new spec language, but then CLauthors must add back in helpful usage metadata/semantics and still need to learn a library API (but I like how those latter two things can be "gradual"). It's a hard space in which to find perfection, but I wish you luck in your attempt!

1 more reply

CableNinja2y ago

Ive sort of managed to implement something to this effect in python, and from another comment made me consider yanking it out to its own library.

I made a process where args are now in a toml file, with some various data for different operations, like whether its available in the CLI or API library, its arg flags, help text required value type, etc. From that, i can generate argparse args, documentation, code for other things, etc. Right now im generating args, docs, and a js code block from the same structure.

Heres the toml file: https://gitlab.com/accidentallythecable-public/prover-suite/...

And some docs that were generated from that: https://gitlab.com/accidentallythecable-public/prover-suite/...

Maybe it will give you some ideas on yours

CableNinja2y ago

I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)

Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...

Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...

akdor11542y ago

Ah sweet, I have been wanting to do pretty much the same thing, have found one or two bits of prior art but nothing that has caught on. Very interested.

j / k navigate · click thread line to collapse

0 comments

6 comments · 4 top-level

cb3212y ago· 2 in thread

jdxcodeOP2y ago

Yeah I investigated. I don’t think it works well that direction. It is appealing and you can see some elements of it in my current design, though that’s a particular part I’m still unsure of.

cb3212y ago

1 more reply

CableNinja2y ago

Ive sort of managed to implement something to this effect in python, and from another comment made me consider yanking it out to its own library.

Heres the toml file: https://gitlab.com/accidentallythecable-public/prover-suite/...

And some docs that were generated from that: https://gitlab.com/accidentallythecable-public/prover-suite/...

Maybe it will give you some ideas on yours

CableNinja2y ago

I ended up breaking that functionality away from the originally linked project. Its now in two parts (in case you go to look for it later)

Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...

Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...

akdor11542y ago

Ah sweet, I have been wanting to do pretty much the same thing, have found one or two bits of prior art but nothing that has caught on. Very interested.

j / k navigate · click thread line to collapse