Documenting environment variables used for options

mkdocs / mkdocs-click

An MkDocs extension to generate documentation for Click command line applications

https://pypi.org/project/mkdocs-click

Apache License 2.0

109 stars 15 forks source link

Documenting environment variables used for options #7

Open nigelm opened 3 years ago

nigelm commented 3 years ago

Environment variables can be used to set option values:-

@click.option(
    "--debug/--no-debug",
    default=False,
    envvar="PRODUCT_DEBUG",
    help="Output debugging logging",
)

However these are not exposed in the CLI documentation.

It has to be admitted that Click's help text also does not expose these at all, so manual addition of this mapping to the docstrings may be needed anyhow.

Many thanks for this plugin for mkdocs - much appreciated

florimondmanca commented 3 years ago

@nigelm That sounds like an interesting enhancement. A few questions:

What would you expect a sample updated rendered usage to be…?
Would this be something better discussed on the click repo, so that --help does output environment variables?

yudai-nkt commented 3 years ago

FWIW, click.Option class has a parameter show_envvar and setting this to True should show an environment variable on the help page. A possible downside of this approach is that this parameter is False by default, so you need to explicitly set show_envvar to True each and every time if you want environment variables to appear in your document.