search

click-contrib / sphinx-click

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

help option is missing from all commands #30

Closed 1oglop1 closed 5 years ago

1oglop1 commented 5 years ago

Hi I have successfully used this awesome plugin. My application has --help to every command or sub command. But docs generated by the plugin does not contain it however click itself yes. Is this intentional or not?

Example out put of sceptre create --help

Usage: sceptre create [OPTIONS] PATH [CHANGE_SET_NAME]

  Creates a stack or a change set.

  Creates a stack for a given config PATH. Or if CHANGE_SET_NAME is
  specified creates a change set for stack in PATH.

  :param path: Path to a Stack or StackGroup :type path: str :param
  change_set_name: A name of the Change Set - optional :type
  change_set_name: str :param yes: A flag to assume yes to all questions.
  :type yes: bool

Options:
  -y, --yes  Assume yes to all questions.
  --help     Show this message and exit.
stephenfin commented 5 years ago

Hmm, good spot. I don't think this is intentional meaning this option (--help) probably isn't set on whatever attribute we're reading to build the document. Marking as a bug so I can investigate at some point.

1oglop1 commented 5 years ago

Guess this might be some click internal trick. I will just mention in my docs that every command has a --help for now.

stephenfin commented 5 years ago

I've looked into this. I can resolve it by changing this line:

https://github.com/click-contrib/sphinx-click/blob/b5e5f89808b11fc2c0bcec180f0c9bf96f04f7e0/sphinx_click/ext.py#L115

If we switch ctx.command.params to ctx.command.get_params(ctx), we get the help message. However, the help message defaults to this:

Show this message and exit.

This isn't that useful and I don't think we probably want to include it as-is. We could do something like check if Command.get_help_option returns anything and provide our own parameter, but I don't think that's all that useful. I'm going to close this as a WONTFIX, but if you disagree please consider reopening with a rationale for why we should include it :smile: