click-contrib / sphinx-click Goto Github PK

The signature for click.MutliCommand.list_commands takes a Click.Context:

class MultiCommand:
...
    def list_commands(self, ctx):
        """Returns a list of subcommand names in the order they should
        appear.
        """

click.MultiCommand.get_commands is similar: get_command(self, ctx, cmd_name)

The function in sphinx-click to get commands from a multicommand is passing the multicommand to itself (instead of the Context) in list_commands and get_commands:

def _get_lazyload_commands(multicommand):
    commands = {}
    for command in multicommand.list_commands(multicommand):
        commands[command] = multicommand.get_command(multicommand, command)

    return commands

Instead, it should take the context from its caller and pass it to list_commands:

def _get_lazyload_commands(ctx):
    commands = {}
    for command in ctx.command.list_commands(ctx):
        commands[command] = ctx.command.get_command(ctx, command)

    return commands

I'm using click version 7.0, and can see the same code in the latest master (297150c7566a38fb672828a36b681792513d99b0).

My sphinx-click does not have a __version__ attribute, but I can see the same code cited above in the latest master (6b928ee1b83e3a554d040d19e95bd3063e464c60)

This is on Python 2.7.13, click 6.6, sphinx 1.6.2, sphinx-click 1.0.2

ClickDirective._load_module (ext.py line 188) is getting a unicode value for module path. This causes __import__ to raise "TypeError: Item in ``from list'' must be str, not unicode".

The fix is easy, one can just do:

module_path = str(module_path)

I'd be happy to make a pull request for this, however, I'm not sure if this would cause issues with Python 3.

Is there a self-contained example demonstrating the use of sphinx-click? For example, I found this repository very helpful for following the procedure to get the recursion to work correctly with sphinx. If there isn't one, I could help put together a Hello World repository with your guidance and assistance.

The most recent reversion of sphinx is 2.1.0, which is not compatible with sphinx-click

ERROR: sphinx-click 2.1.0 has requirement sphinx<2.1,>=1.5, but you'll have sphinx 2.1.0 which is incompatible.

Hello, I am trying to document the CLI here.
I have some general questions:

1. I am interested in generating a separate documentation page per click command sort of like how sphinx already does for typical python code. Is it possible to do this? Would I just have to manually create separate .rst files per click group?
2. Is it possible to script / automate (recursively) things such that there is no need to manually add each group in index.rst?
3. Is it possible to generate a tree or table of click groups and commands just like typical sphinx documentation?

The developer of the CLI I am trying to document appears to have used some custom click configurations to enable autocompletion etc. Consequently, I am not able to follow the Hello World example provided in the documentation. I get the following error when trying to document their CLI.py this way in index.rst:

.. click:: datafed:_cli
  :prog: datafed
  :nested: full

This is the error I get:

/DataFed/python/datafed_pkg/docs/source/index.rst:28: WARNING: Module "datafed" has no attribute "_cli". 

How should I be configuring index.rst correctly?

Many thanks in advance!

The "join()" call in ^^ this ^^ line should probably say ' | '.join(str(_) for _ in opt.type.choices) instead.

Not sure, there may be other related issues, but this is the one that got me..

When we use sphinx-click to generate the documentation for a command which has sub-commands, the sub-commands which have been marked as 'hidden' are still being generated as command options in the top-level command's documentation.

For example, say I have the command 'foo': which has the sub-commands 'bar' and 'baz'

$ foo
Usage: foo [OPTIONS] COMMAND [ARGS] ...

  Foo the frobinator

Options:
   --hello      Say hello

Commands:
   bar          bar something
   baz          baz something

I wish to deprecate foo baz, so I have now marked baz as hidden and added a new command. However, when we generate the documentation for foo:

.. click:: my_project._frontend.cli:foo
   :prog: The foo command

both bar and baz will still be documented as valid sub-commands.

Aside

Thank you for the quick fix of the issue that I had originally filed (#31 ), really appreciate that.
In hindsight, I don't think that I gave enough detail of my problem in #31, and from a quick (and admittedly, naive) look at the fix, this looks like we won't generate documentation for a hidden command that we explicitly try to generate documentation for, e.g. following on from the example above:

.. click:: my_project._frontend.cli:baz
   :prog: The hidden baz command

I just noticed that all the click commands are not appearing in autodoc-generated pages.

Check out the original module:
https://github.com/isomeric/isomer/blob/master/isomer/tool/remote.py

vs. the generated click documentation:
https://isomer.readthedocs.io/en/latest/manual/Administration/tool.html#iso-remote

vs. the generated autodoc documentation:
https://isomer.readthedocs.io/en/latest/dev/packages/isomer/isomer.tool.remote.html

This might confuse readers a lot, especially since i found no sane way to link to the click documentation pages in all of the concerned autodoc pages.

As mentioned in the Click documentation, a Command instance may have an epilog, which is written to the formatter after the command's usage, help text, and options.

For a given command, if the command has an epilog, the epilog should be rendered as the last section for that command.

I'm using sphinx-click to render my documentation in HTML and Markdown, and have come across an incompatibility with the click-option-group library. The groups are rendered with internal names instead of the help records they expose.

RequiredMutuallyExclusiveOptionGroup are output in a strange way, for example:

The click-option-group creator responded:

It seems, sphinx-click ignores get_help_record method of Option class and re-implements it in ext:

sphinx-click/sphinx_click/ext.py

Line 31 in 7a7240b

def _get_help_record(opt):

Unfortunately, this means that we cannot customize this behavior in sphinx-click ext and we lose any custom help formatting for the options in sphinx docs. We could create an issue in sphinx-click about it.

Is there a way to hide/disable output for this element, or support it?

The issue in click-option-group is here: click-contrib/click-option-group#4

Currently you document command like this (see here):

.. program:: cli  (including help text)
.. code-block:: shell
.. rubric:: Options
.. rubric:: Arguments

Click in the console help output documents commands like this

Usage (corresponding to your shell code block)
Help text
Options

Click docs at http://click.pocoo.org/dev/arguments/ say

Click will also not attempt to document arguments for you and wants you to document them manually in order to avoid ugly help pages.

and expects arguments to be documented in the help text. Given that arguments don't support a help the argument docs you are generating doesn't really contain much useful information.

How about removing arguments docs completely, i.e. follow the lead of click for the help page?

Or if you want to keep it: how about putting the argument description before the options, i.e. closer to where arguments are usually described for click commands, and add a config option for click-sphinx users to select if they want to emit the arguments rubric (for me it would be no, I would like to not have it)?

A more minor question / change request I have is whether it would be better to put the command help text after the usage line. This is then how click and man pages in general do it, and what I find most readable to have the usage line at the top.

@stephenfin - Let me know what you think. If you agree with any of the suggestions I'd be happy to make a pull request.

Getting warning building with sphinx 1.6.2

sphinx_click/ext.py:6: RemovedInSphinx17Warning: sphinx.util.compat.nd will be removed in Sphinx 1.7, please use the standard library version instead.
  from sphinx.util.compat import Directive

I'm trying to cross-reference a CLI option:

.. click:: mypackage.cli:cli
  :prog: myprog

My CLI looks something like this:

[...]
click.option("-v", "--verbose", is_flag=True, help="Print verbose messages.")
def cli(verbose, force, extensions, output_dir, source_dir):
    [...]

I tried :option:`--verbose` and also :option:`-v` which both should work according to Sphinx docs.

If I use it after the click:: mypackage.cli:cli everything works as expected.

If I use it before it, the compilation of the docs fail with:

Warning, treated as error:
/.../docs/usage.rst:29:unknown option: --verbose

Not sure though if this is a) a problem how I'm using Sphinx, b) problem in Sphinx or c) problem in sphinx-click.

Any help highly appreciated! Thx

Versions

Python-3.7
click-7.0
sphinx-click-2.0.1
sphinx-2.0.0

Great project btw! 👍

Hey @untitaker could I get admin rights on this repo so I can manage secrets. Currently I only have something approaching Maintainer, I suspect. Travis CI is dead and I want to migrate to GitHub Actions 🔨

I have a click command that looks like the following:

import click

@click.command()
@click.option('--name', help='Name to say hello to.', required=True, type=str)
def hello(name):
    """Prints hello to name given.
      
    Examples
    ----------
    
    .. code::bash

      my_cli hello --name "Jack"
    """
    print("Hello", name)

The example code is showing up in my docs, but the title ("Examples" in this case) isn't. I was wondering why this is happening? Typically, I can use reStructured Text in my docstrings to document my code.

Thanks for your help! I appreciate your work on this project!

Click 8.0.0 was just released but it seems it makes sphinx-click revert to 2.5.0. I've tested a project forcing both click 8.0.0 and sphinx-click 2.7.1 and it seems to compile fine and cannot see any obvious problems.

Hi there!

Thank you for this nice project.

Sphinx 3 is out, could this work with it?

I am running into a very weird issue. The documentation is fine for sphinx-click when the file name is hello_world.py or a.py, but when the name is changed to let's say ted.py, it would not work. Can anyone help me with that?

I want to create an entry for each sub-command:

.. click:: my_project.cli:main
    :prog: my-project
    :show-nested:
    :commands: template

Some text in my documentation 

.. click:: my_project.cli:main
    :prog: my-project
    :show-nested:
    :commands: package

But the "problem" is that the docstring from the command main is written twice.

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

template
[docstring of template command]

my-project template [OPTIONS]

Options
[options from template]

Some text from my documentation 

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

package
[docstring of package command]

my-project package [OPTIONS]

Options
[options from package]

Do you know some way to avoid this "duplication"? I mean how can I hide the sections

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

It's possible?

My click parser has the commands sorted alphabetically

Usage: cmd_parser.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  camera     Handles the cameras.
  centre_up  Centres the field.
  ds9        Handles the DS9 communication
  help       Shows the help.
  ping       Pings the actor.
  status     Returns the status.
  tcc        Handles the TCC connection
  version    Returns the version.

However, the documentation generated by sphinx-click shows the commands in an apparently random order (e.g., status, help, ds9, etc).

Our use case is to have an option which is common to multiple commands.
This option has an envvar parameter.
This gives a warning.
I think that this is a valid, not warning-worthy error.
Perhaps sphinx-click should differentiate the built environment variable blocks somehow.

A small reproducible case follows:

hello.py:

import click

@click.command()
@click.option('--foo', envvar='EXAMPLE')
def A(foo):
    pass

@click.command()
@click.option('--foo', envvar='EXAMPLE')
def B(foo):
    pass

source/index.rst:

.. click:: hello:A
   :prog: hello

.. click:: hello:B
   :prog: hello

Building the docs shows the following error:

hello:1: WARNING: Duplicate explicit target name: "cmdoption-hello--foo".
/Users/dev/Workspace/sphinx-envvar/source/index.rst:3: WARNING: Duplicate ID: "envvar-EXAMPLE".

Found with @mhrabovcin.

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.

Simple example:

sudo: false
language: python
python:
  - "2.7"
  - "3.6"
install: pip install tox-travis
script: tox

A few things that would be useful to have for the options, if set:

• The type
• The possible values, for multiple choice options
• The default value, if any.
• Whether it's a boolean (is_flag)

When using Custom Multi Commands sphinx-click doesn't document the subcommands because multicommand.commands is empty

A quick solution on click's side would be to manually populate the commands attribute by loading all the commands but if you're trying to lazy load on purpose you may cry about performance issues.

class MyGroup(click.MultiCommand):
    """Dynamic group loader class."""

    folder = None

    def __init__(self, **kwargs):
        click.MultiCommand.__init__(self, **kwargs)
        self.commands = self._get_commands()

    def _get_commands(self):
        commands = {}
        for command in self.list_commands(self):
            commands[command] = self.get_command(self, command)

        return commands

I also patched a partial fix in omercnet@7497618 but it doesn't show the MultiCommand name in the docs (returns None), if anyone is willing to help finish it off that would be great :)

No changelog when pyup is updating

cihai/cihai-cli#6

Click 7.0 allows us to declare commands as 'hidden', by defining something along the lines of:

@cli.command(short_help="Foo some bar", hidden=True)
@click.argument('bar')
@click.pass_obj
def foobar(bar):
    click.echo("Bar foo'd")

Notice the 'hidden=True'.

Now, if this command exists as a subcommand of a higher level command, when generating documentation for the higher level command, this sub command will appear within the documentation.
Please see this downstream issue for a more specific example.

Ideally, hidden commands should not be present within the generated documentation.

When you have type=click.Choices(['a', 'b', 'c']) in a Click option, it would be very helpful to include those options in the generated help output.

For example, the auto-generated --help output has

  --log-level [NOTSET|DEBUG|INFO|WARNING|ERROR|FATAL]

but the generated HTML just says

--log-level <log_level>

I'm having trouble mixing click directives with custom documentation (extended explanations etc.) because click directives are nested under the previous section.

In the use case below I want to have a flat section level:

===
CLI
===

.. _prog status:

.. click:: prog.cli.command:status
   :prog: prog status

prog command status
-------------------

See `prog status`_.

.. click:: prog.cli.command:test
   :prog: prog command test

Here, I expected to have

# CLI
## prog status
## prog command status
## prog command test

but ended up with

# CLI
## prog status
## prog command status
### prog command test

Is it possible to add a feature that let's you either control the section level or omit the section entirely, e.g.

prog command test
-----------------

.. click:: prog.cli.command:test
   :prog: prog command test
   :nofirstsection:

As discussed in #2, if you define a command with no help text, the build fails like so:

TypeError: expected string or bytes-like object

Exception occurred:
  File "/tmp/git/.tox/docs/lib/python3.5/site-packages/docutils/statemachine.py", line 1520, in string2lines
    astring = whitespace.sub(' ', astring)
TypeError: expected string or bytes-like object

This is because we don't ensure descriptions are available before attempting to use them.

Thank you for working on this project, I've used it for a while and it's really slick, kudos.

I have noticed that when ANSI escape sequences are used to denote colour of the text to use when rendering the text in the terminal, they are rendered "as-is". The sphinx-click parses the strings using statemachine.string2lines(); it does not show any consideration for any eventual escape sequences that may be present -- this results in raw escape sequences text being rendered in the HTML documentation.

I believe it may be beneficial to strip the escape sequences given that it's quite likely developers of the click applications may take advantage of custom colorisation of their help documentation that is going to be rendered in the terminal with pretty colours.

To illustrate the problem:

os_support = f'\033[94m{os_support}\033[0m'
print(os_support)
print(re.sub(r'\x1b\[([0-9,A-Z]{1,2}(;[0-9]{1,2})?(;[0-9]{3})?)?[m|K]?', '', os_support))

The rendered HTML docs for the colorised epilog:

Do you think it would be reasonable to strip the escape codes out of any string that is going to be read from the command line documentation (description, subcommands, options, etc) using a regexp such as the one used in the example above? Are there any complications that I may have overseen?

Many thanks.

This may be a theme issue, and not a sphinx-click one, but when the documentation is rendered, nested subcommands have the same fontsize as their parents. For instance, in the screenshot, show_chart is a subcommand of ds9, but their sizes are identical. This makes it hard to know what is a command and what a subcommand. Note that in the sidebar, show_chart correctly appears nested under ds9.

Click has the following option: https://click.palletsprojects.com/en/7.x/documentation/?highlight=docstring#truncating-help-texts

@click.command()
@click.pass_context
def cli(ctx):
    """First paragraph.

    This is a very long second
    paragraph and not correctly
    wrapped but it will be rewrapped.
    \f

    :param click.core.Context ctx: Click context.
    """

with the CLI output

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

  This is a very long second paragraph and not correctly wrapped but it will
  be rewrapped.

Options:
  --help  Show this message and exit.

however, it turns out that the sphinx-click contrib will also show the same help output, instead of using the full docstring. It's clear that this was geared towards being used with sphinx.

I am having an issue with allow_extra_args.

I get the following error:

Exception occurred:
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/click/core.py", line 254, in __init__
    allow_extra_args = command.allow_extra_args
AttributeError: module 'scripts.cfd' has no attribute 'allow_extra_args'

The whole backtrace is:

# Sphinx version: 1.6.3
# Python version: 3.6.0 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.6
# Last messages:
#   updating environment:
#   
#   6 added, 0 changed, 0 removed
#   
#   reading sources... [ 16%] api
#   
#   reading sources... [ 33%] authors
#   
#   reading sources... [ 50%] cfd
#   
# Loaded extensions:
#   alabaster (0.7.10) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/autodoc.py
#   sphinx.ext.intersphinx (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/intersphinx.py
#   sphinx.ext.todo (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/todo.py
#   sphinx.ext.autosummary (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/autosummary/__init__.py
#   sphinx.ext.viewcode (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/viewcode.py
#   sphinx.ext.coverage (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/coverage.py
#   sphinx.ext.doctest (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/doctest.py
#   sphinx.ext.ifconfig (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/ifconfig.py
#   sphinx.ext.imgmath (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/imgmath.py
#   sphinx.ext.napoleon (1.6.3) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/ext/napoleon/__init__.py
#   sphinx_click.ext (unknown version) from /home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx_click/ext.py
Traceback (most recent call last):
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/cmdline.py", line 306, in main
    app.build(opts.force_all, filenames)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/application.py", line 339, in build
    self.builder.build_update()
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 331, in build_update
    'out of date' % len(to_build))
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 344, in build
    updated_docnames = set(self.env.update(self.config, self.srcdir, self.doctreedir))
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/environment/__init__.py", line 583, in update
    self._read_serial(docnames, self.app)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/environment/__init__.py", line 602, in _read_serial
    self.read_doc(docname, app)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/environment/__init__.py", line 723, in read_doc
    pub.publish()
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/core.py", line 217, in publish
    self.settings)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx/io.py", line 74, in read
    self.parse()
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/__init__.py", line 185, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2980, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 326, in section
    self.new_subsection(title, lineno, messages)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 394, in new_subsection
    node=section_node, match_titles=True)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    node=node, match_titles=match_titles)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2318, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2330, in explicit_construct
    return method(self, expmatch)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2073, in directive
    directive_class, match, type_name, option_presets)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2122, in run_directive
    result = directive_instance.run()
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx_click/ext.py", line 285, in run
    return self._generate_nodes(prog_name, command, None, show_nested)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/sphinx_click/ext.py", line 219, in _generate_nodes
    ctx = click.Context(command, info_name=name, parent=parent)
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/cfd-venv/lib/python3.6/site-packages/click/core.py", line 254, in __init__
    allow_extra_args = command.allow_extra_args
AttributeError: module 'scripts.cfd' has no attribute 'allow_extra_args'

My code uses context to set allow_extra_args, and looks like:

@click.group()
@click.pass_context
def cli(ctx):
    ctx.allow_extra_args = False
    ctx.obj = Cfd()

However, I have found that even if I comment the line touching ctx.allow_extra_args I still get the problem. Maybe this is incompatible with click 6.7?

The name of my program is misaligned by being further indented than it should be. E.g.:

TODOMAN(1)                Todoman               TODOMAN(1)

NAME
       todoman - a simple, standards-based, cli todo

TODO
          todo [OPTIONS] COMMAND [ARGS]...

       Options

Note than todo [OPTIONS is further right than it should be. For comparison, man(1):

MAN(1)                    Manual pager utils                    MAN(1)

NAME
       man - an interface to the system reference manuals

SYNOPSIS
       man [man options] [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [man options] [section] term ...

Also, rather than TODO, this should say SYNOPSIS.

Hi, I'm encountering an error when using sphinx-click in a project that uses sphinx automocking.

When I run sphinx-build I get the following error:

/Users/dgibson/dagster/docs/sphinx/sections/api/apidocs/libraries/dagster-celery.rst:117:Failed to import "worker_start_command" from "dagster_celery.cli". The following exception was raised:
Traceback (most recent call last):
  File "/Users/dgibson/.pyenv/versions/3.8.3/envs/docsnodeps/lib/python3.8/site-packages/sphinx_click/ext.py", line 385, in _load_module
    mod = __import__(module_name, globals(), locals(), [attr_name])
  File "/Users/dgibson/dagster/python_modules/libraries/dagster-celery/dagster_celery/cli.py", line 6, in <module>
    from celery.utils.nodenames import default_nodename, host_format
ModuleNotFoundError: No module named 'celery'

I'm sure that I have celery in the list of autodoc_mock_imports (and removing it from that list breaks other sphinx imports that are not using sphinx-click). I'm using sphinx-click 3.0.1 (and Sphinx 3.5.2).

Is this behavior expected / are there workarounds for mocking imports in modules imported by sphinx-click? Thanks for your help!

First of all, thanks for this very nice package! It makes the documentation of click based application very easy.

We are developing a command line tool and we have some private sub-commands that we would like to exclude from the doc.
I know that I can select the subcommands that are documented using the :commands: directive.

However, most sub-commands need to be included in our case so having a easy way to exclude "private" commands would be very nice, either having a :exclude: directive or not documenting certain patterns, for instances sub-commands starting with _. WDYT?

Hi, I'm using the most current version of Sphinx (3.4.2), Sphinx-Click (latest) and click (7.1.2).

My situation is like this:

• I have a separate package with a click cli, which has a group named main (module modA.cli in package packageA)
• in another package (module modB.cli in package packageB) I also have a CLI and import the group main from modA.cli as submain
• I add the submain group to the modB.cli command groups as a subcommand.
  If I now execute packageB I will see the subcommand submain as possible choice. In the generated documentation it however will still appear as main (name from modA.cli I would suppose)

Not sure if the example code can reproduce this or if it has to be separate packages (not just modules)...

# packageA modA.cli

import click

@click.group()
def main():
    pass


@main.group()
def subA():
    pass

# packageB modB.cli

import click
from modA.cli import main as submain

@click.group()
def main():
    pass

main.add_command(submain, "submain")  # <-- here I add the commandgroup from packageB and rename the command
# without renaming here, it will show up as `main` in the CLI

@main.group()
def subB():
    pass

I will then call the modB.cli:main() entry point.

Documentation is dead simple:

.. click:: modB.cli:main
  :prog: packageB
  :nested: full

I noticed that in your requirement.txt you are limiting the sphinx version to 1.5>, <2.3

Are there any known issue or something more serious for this limitation being added?

Otherwise, I would suggest modifying to "sphinx > 1.5", allowing new versions of sphinx to be used as normally.

My motivation for this question is because I'm updating the recipe for conda (conda-forge/sphinx-click-feedstock#6)

@stephenfin do you agree with the modification?

In docs/usage.rst, the extension name to be included in conf.py / extensions should be mentioned. Can be fixed by copying over the paragraph from readme.rst:

Enable the plugin in your Sphinx conf.py file:

    extensions = ['sphinx_click.ext']

Thanks for the great module, I'm trying to use it a bit.

The usage example in the readme doesn't match the docs: https://sphinx-click.readthedocs.io/en/latest/usage/#example and options :module: and :func: don't appear to work in 1.0.0

Currently click options specified with count=True, useful for verbose flags for example, are not supported in N-length form:

Specify :option:`-vv` to enable debug output.

The above issues the following warning while building with Sphinx:

WARNING: unknown option: -vv

As is documented in click here, the docstrings for click commands are expected to contain \b characters before a paragraph which should not be made to wrap.

This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.

This works well for click's help output, but is also broken for the click-man generated man pages, and for sphinx-click generated html (although the man pages are slightly less broken than the html).

See this example of the breakage and compare with the corresponding help output below:

Usage: bst show [OPTIONS] TARGET

  Show elements in the pipeline

  By default this will only show the specified element, use the --deps
  option to show an entire pipeline.

  FORMAT
  ~~~~~~
  The --format option controls what should be printed for each element,
  the following symbols can be used in the format string:

      %{name}     The element name
      %{key}      The abbreviated cache key (if all sources are consistent)
      %{full-key} The full cache key (if all sources are consistent)
      %{state}    cached, buildable, waiting or inconsistent
      %{config}   The element configuration
      %{vars}     Variable configuration
      %{env}      Environment settings
      %{public}   Public domain data

  The value of the %{symbol} without the leading '%' character is understood
  as a pythonic formatting string, so python formatting features apply,
  examle:

      build-stream show target.bst --format \
          'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'

  If you want to use a newline in a format string in bash, use the '$'
  modifier:

      build-stream show target.bst --format \
          $'---------- %{name} ----------\n%{vars}'

Options:
  -d, --deps [all|build|run]  Optionally specify a dependency scope to show
  --order [stage|alpha]       Staging or alphabetic ordering of dependencies
  -f, --format FORMAT         Format string for each element
  -a, --arch TEXT             The target architecture (default: x86_64)
  --variant TEXT              A variant of the specified target
  --help                      Show this message and exit.

1. display only listed subcommands

.. click:: my_package.cli:cli
   :prog: my_package
   :commands: login, run, stop  # preserve the order!

2. do not show any subcommand

.. click:: my_package.cli:run
   :prog: my_package.run
   :commands:  # or :no-commands:

python 3.4.6
sphinx-click 1.0.3
sphinx 1.5.3

Currently if there is an error when building the documentation any failures importing will be reported like this:

reading sources... [100%] pages/my_page                                                                                                                                                                                                
/path/to/pages/my_page.rst:1: ERROR: Failed to import "cli" from "src.cli.__main__"

In my case this import was failing due to a silly syntax error I introduced somewhere in my source code.

It would be nice to have that stack trace of the syntax error pushed up to the command's output so it's easier to diagnose the cause of the failed import.

Thanks.

Sphinx v2.0.0 was released a month ago, and has since started to be been adopted into build chains. When sphinx-click is build from the current master, it works with sphinx without any issues, as far as I have tested. But to actually use it in production, I'd need to get it from pypi instead of building it.

Could a new version be build from the current master and be released to pypi?

I am using a following versions of packages:

click==7.1.2
Sphinx==3.2.1
sphinx-click==2.5.0

Then I added to my project directive as in the usage documentation:

.. click:: __main__:cli
   :prog: gitp
   :show-nested:

But when I try to build documentation with sphinx-build I get the error: Unknown directive type "click".

You can see my code here: https://github.com/staticdev/git-portfolio/blob/master/src/git_portfolio/__main__.py

Thanks for writing this extension!

Considering the following setup:

.. click:: test:hello
   :prog: test
   :show-nested:

It would be nice if one can refer to the resulting documentation (e.g. for one of the nested commands) just as one can reference normal functions via the directives documented in http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects .

I.e. it would be nice if something like :py:click-command:'test.hello' would insert a link to the relevant part of the documentation.

I have a lot of subcommands, so I'd like to show them in the table of contents so they are easy to find. Currently I'm just getting the top-level command in the table of contents. I tried changing the subcommand directive from object to program, but that didn't seem to help. Is it possible to optionally allow subcommands in the table of contents?

Thanks for sphinx-click. I tried it with the git example from the click docs and unfortunately it fails with allow_extra_args even though the program itself works fine so it might be due to some interaction between click and sphinx.

The program is:

import os
import click


class Repo(object):
    def __init__(self, home=None, debug=False):
        self.home = os.path.abspath(home or '.')
        self.debug = debug


@click.group()
@click.option('--repo-home', envvar='REPO_HOME', default='.repo')
@click.option('--debug/--no-debug', default=False,
              envvar='REPO_DEBUG')
@click.pass_context
def cli(ctx, repo_home, debug):
    ctx.obj = Repo(repo_home, debug)

@cli.command()
@click.argument('src')
@click.argument('dest', required=False)
def clone(src, dest):
    pass


@cli.command()
@click.argument('src')
@click.argument('dest', required=False)
@click.pass_obj
def clone(repo, src, dest):
    pass

if __name__ == '__main__':
    print('starting')
    cli(obj={})

I call this git.py and put it inside a git subfolder with an empty __init__.py that looks like:

git
  |- git
  |    |- __init__.py
  |    \- git.py
  \- docs
      |- git.rst
      |- index.rst
       \- conf.py

And the I have a git.rst that looks like:

.. click:: git:git
   :prog: git
   :show-nested:

When I run make html in docs I get:

reading sources... [ 50%] git                                            
Exception occurred:
  File "/home/pmatos/.pyenv/versions/3.6.0/envs/git-venv/lib/python3.6/site-packages/click/core.py", line 254, in __init__
    allow_extra_args = command.allow_extra_args
AttributeError: module 'git.git' has no attribute 'allow_extra_args'
The full traceback has been saved in /tmp/sphinx-err-22udtufb.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:53: recipe for target 'html' failed