Imho this is a bad pitch. It took me a moment to realize that you have already solved the problem that you're proposing (and the "challenge" is only meant to pitch the solution).
Given the elegance of that very solution I think this marketing stunt is entirely unneeded and actually harmful; it's confusing and you miss out on getting a descriptive headline such as "Generate OptParser from code comment!".
That said... Brilliant idea!
I'm definitely trying out docopt for my next project.
And I have a counter-challenge for you:
How about making docopt work with nested commands? I.e. multiple methods could have a docopt-style comment and they would smartly merge to enable usages such as "mygit remote show --help", where 'show' is a subcommand of 'remote', with its own set of parameters and a matching help-page.
If you can work that one out then docopt could become the defacto standard for generating even complex OptParsers.
I think it's a great pitch, because the pseudo-pitch appeals to exactly the people who would be interested in this. "Ha! I've got this licked, I'll just whip out argparse ... Wait ... Oh!"
For me, your new presentation worked brilliantly. The short while it took me to get what was going on, was exactly what caused me to keep reading. Granted, it is a bit of a bait and switch, but a pleasant one.
I too think the pitch is brilliant - specially when you think about the target audience - folks who get turned on by the word "Challenge", er developers, and most of them must have felt the need for something like this at some point of their life("Some day I'll have to write clean & DRY way ...").
Only thing different might be instead of giving the solution on that page itself - a hyperlink to the solution which takes you to docopt.org landing page
I agree. I thought, interesting challenge, although not interesting enough for me to actually try it. I wonder if he has any example solutions that I could look through. Huh? Ooooh.
If I had just seen it presented straight out as, "Parse arguments based on docstrings," I doubt it would have been nearly as memorable.
But I'd strongly vote for making it possible to annotate multiple functions and merging their respective doc-strings smartly.
I don't think you'd want to express the entire syntax-tree of a reasonably complex program (e.g. 'git') in a single doc-string. Not only would that turn into a mess, but you'd also lose modularity. I.e. subcommands often need to be dynamically generated (e.g. depending on loaded modules) and not all subcommands may be available at all times.
I'm also a fan of idea of using function-docstrings for separate subcommand help-screens. Problems: (1) exact API, (2) how to do that in non-python implementations. You (and everyone) is very welcome to suggest APIs for that in issues:
https://github.com/docopt/docopt/issues
Given the elegance of that very solution I think this marketing stunt is entirely unneeded and actually harmful; it's confusing and you miss out on getting a descriptive headline such as "Generate OptParser from code comment!".
That said... Brilliant idea!
I'm definitely trying out docopt for my next project.
And I have a counter-challenge for you:
How about making docopt work with nested commands? I.e. multiple methods could have a docopt-style comment and they would smartly merge to enable usages such as "mygit remote show --help", where 'show' is a subcommand of 'remote', with its own set of parameters and a matching help-page.
If you can work that one out then docopt could become the defacto standard for generating even complex OptParsers.