More anchors + new features: :hide-header:, :nested: complete, :post-process: #147
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add anchors to all the Click components (i.e. groups and commands), along with another general one for options so that now using the full path of the component with separating dashes is always a valid reference. E.g. for a group "mygroup", command "mycommand" and option "-myoption", all of the following work: :ref:`My Group <mygroup>` :ref:`My Command <mygroup-mycommand>` :ref:`My Option <mygroup-mycommand-myoption>` :option:`My Option <mygroup-mycommand -myoption>`
Adding :hide-header: to the directive will hide the title, description and usage and only show the commands. This also means that the commands will not be under a single section, but rather add a section each to where the directive is located. The ":nested: complete" option shows the name, description, usage, short command overview (basically the entire ":nested: short" option) followed by the details of the commands from the ":nested: full" option.
By providing the option ":post-process: module.path:funcion", the user can direct the directive to run the provided function on the command and its generated node for each command processed. This allows for full per-command customization of the output.
The usage was removed when :hide-header: was used with full nesting before. This should make it behave the same as it does with short nesting.
This adds documentation for `complete` nesting, `:hide-header:` and `:post-process:`.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This adds the following features:
:hide-header:option: omits the title and description from the output.:nested: completeoption: 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. =):post-process: path.to.module:func_nameoption: 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 groupgrp, commandcmd, an option that has the flags-fand--flagand an environment variableenvthat provides a default for it, the following anchors will be created:grp-cmd-fgrp-cmd-flaggrp-cmd-f-envgrp-cmd-flag-envThis has a caveat which I haven't dealt with, which is collisions.
Having an option with the flag names
-fand--fwould cause the same anchor to be created twice. Similarly a command calledcmdwith the flag--some-flagand a command calledcmd-somewith the flag--flagwould both create the anchorcmd-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+ commandsome-cmd+ optionoptwould yield the same option anchor as groupgrp-some+ commandcmd+ optionopt, 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.
Tasks
reno)tox)Further details
This is the same PR as #100, fixed to work with the modern code.
I wanted to get this open already so I used what I have now - I'll look at
renolater for the release notes.This can also use some more tests.