search

click-contrib / sphinx-click

A Sphinx plugin to automatically document click-based applications
MIT License
212 stars 57 forks source link

More anchors + new features (WIP): :hide-header:, :nested: complete, :post-process: #100

Closed TomerGodinger closed 2 months ago

TomerGodinger commented 2 years ago

This adds the following features:

  1. :hide-header: option: omits the title and description from the output.
  2. :nested: complete option: produces a fuller listing with title, description, usage, short summary and then full nested details. Feel free to change the name to whatever you want if you choose to keep it. =)
  3. :post-process: path.to.module:func_name option: invokes the specified function in the specified module on the list of generated nodes for each command. The function should get the command used and the list of nodes that were generated.

This also adds quite a few new anchors for cross-referencing - namely one for each .. program:: directive, and for options and environment variables, an anchor is added per option name. For example, for a command group grp, command cmd, an option that has the flags -f and --flag and an environment variable env that provides a default for it, the following anchors will be created:

This has a caveat which I haven't dealt with, which is collisions. Having an option with the flag names -f and --f would cause the same anchor to be created twice. Similarly a command called cmd with the flag --some-flag and a command called cmd-some with the flag --flag would both create the anchor cmd-some-flag. It may be a good idea to change the format so it's injective. This actually applies to existing anchors as well, e.g. group grp + command some-cmd + option opt would yield the same option anchor as group grp-some + command cmd + option opt, if I'm not mistaken. A decision not to support this would be valid, of course, but it's something that begs consideration at the least.

As mentioned in the title, this is not a finished, polished product. While it does seem to work in general, I haven't tested it thoroughly, and since it adds new anchors, it currently breaks nearly all the existing tests, as they don't expect to get them.

TomerGodinger commented 2 years ago

Thanks for all the suggestions. I'll make the changes when I can and submit another PR (or can I update this one instead?). Sorry for the mess. This is the first PR I've made and I'm not well-versed in how it works.

TomerGodinger commented 2 years ago

A good start. Got a few suggestions inline. Tests would really help a lot here. Also, I see a couple of cases where you add things in the first patch and remove them again in the second or third one. Can you rebase and clean these up before force pushing updates?

Can you please tell me which cases of adding and removing the same things you're referring to? The only such thing I've found was that debug print, which needed to disappear altogether. I don't see anything else of the sort.

TomerGodinger commented 2 years ago

@stephenfin Just a friendly reminder that I'm waiting for your replies before I update this PR.

TomerGodinger commented 2 years ago

I've pushed an update based on everything we've discussed. Also fixed the tests and added another one for the complete nesting. Tell me what you think when you can please.

stephenfin commented 2 years ago

I've pushed an update based on everything we've discussed. Also fixed the tests and added another one for the complete nesting. Tell me what you think when you can please.

Oh, I missed this reply. Will look later today or tomorrow 🙈

stephenfin commented 2 years ago

@TomerGodinger I reworked a few of the commits and fixed broken type checks but the general content should be the same. Could you take a look over and see if you're happy with it? Could you update the docs just to reflect the new changes? Once that's done, I think we're good to go.

PS: You can probably drop WIP from the PR title now too :smile:

TomerGodinger commented 2 years ago

Hey, sorry for the delay. I haven't had time to do this, but I'll try to get on it as soon as I can.

sravel commented 1 year ago

hello I want to use the option :hide-header: can you fix and valid merge request?

sravel commented 5 months ago

will this request be included?

stephenfin commented 5 months ago

@sravel Someone needs to pick this up again as I assume @TomerGodinger no longer needs this.

TomerGodinger commented 5 months ago

Ugh, I'm really sorry, I completely forgot about this. I rebased, fixed the conflicts and updated the tests to recognize the new anchors, but I'm afraid I don't have the capacity right now to get back into this much beyond that. It'll take at least several weeks for me to be available to take this up again. You can take this up and continue without me if you'd like to, or wait for me to have some time free up for it.

Again, sorry for the holdup.

stephenfin commented 5 months ago

@TomerGodinger No issues. There's no panic with this so I'm happy to wait.

stephenfin commented 2 months ago

Closing this for now. If you're able to get back to this, please feel free to reopen.