Skip to content

Click v8.2.X breaks docs build with unexpected keyword argument 'ctx' #2614

Description

@matthewfeickert

For click v8.1.8

pushd docs
make html

runs successfully, but for click v8.2.0+

cd docs
uv pip install --upgrade 'click<8.2.1' && make clean && make html

it fails with

updating environment: [new config] 165 added, 0 changed, 0 removed
reading sources... [ 76%] cli
Exception occurred:
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/click/core.py", line 3075, in make_metavar
    var = self.type.get_metavar(param=self, ctx=ctx)
TypeError: DocumentedChoice.get_metavar() got an unexpected keyword argument 'ctx'
The full traceback has been saved in /tmp/sphinx-err-q7wbz8va.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!
make: *** [Makefile:57: html] Error 2
$ uv pip show click
Using Python 3.13.6 environment at: /home/feickert/Code/GitHub/scikit-hep/pyhf/.venv
Name: click
Version: 8.2.0
Location: /home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages
Requires:
Required-by: click-completion, papermill, pyhf, sphinx-click

where the full traceback mentioned in the logs is

Traceback

# Platform:         linux; (Linux-6.8.0-79-generic-x86_64-with-glibc2.39)
# Sphinx version:   8.1.3
# Python version:   3.13.6 (CPython)
# Docutils version: 0.21.2
# Jinja2 version:   3.1.6
# Pygments version: 2.19.2

# Last messages:
#   babel
#   
#   
#   reading sources... [ 76%]
#   citations
#   
#   
#   reading sources... [ 76%]
#   cli
#   

# Loaded extensions:
#   sphinx.ext.mathjax (8.1.3)
#   alabaster (1.0.0)
#   sphinxcontrib.applehelp (2.0.0)
#   sphinxcontrib.devhelp (2.0.0)
#   sphinxcontrib.htmlhelp (2.1.0)
#   sphinxcontrib.serializinghtml (2.0.0)
#   sphinxcontrib.qthelp (2.0.0)
#   sphinx.ext.autodoc.preserve_defaults (8.1.3)
#   sphinx.ext.autodoc.type_comment (8.1.3)
#   sphinx.ext.autodoc.typehints (8.1.3)
#   sphinx.ext.autodoc (8.1.3)
#   sphinx.ext.autosummary (8.1.3)
#   sphinx.ext.coverage (8.1.3)
#   sphinx.ext.ifconfig (8.1.3)
#   sphinx.ext.viewcode (8.1.3)
#   sphinx.ext.githubpages (8.1.3)
#   sphinx.ext.intersphinx (8.1.3)
#   sphinxcontrib.bibtex (2.6.5)
#   sphinx.ext.napoleon (8.1.3)
#   sphinx_click.ext (unknown version)
#   nbsphinx (0.9.7)
#   sphinx_issues (5.0.1)
#   sphinx_copybutton (0.5.2)
#   xref (unknown version)
#   jupyterlite_sphinx (unknown version)
#   pydata_sphinx_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/cmd/build.py", line 514, in build_main
    app.build(args.force_all, args.filenames)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/application.py", line 381, in build
    self.builder.build_update()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 358, in build_update
    self.build(
    ~~~~~~~~~~^
        to_build,
        ^^^^^^^^^
        summary=__('targets for %d source files that are out of date')
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        % len(to_build),
        ^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 385, in build
    updated_docnames = set(self.read())
                           ~~~~~~~~~^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 502, in read
    self._read_serial(docnames)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 567, in _read_serial
    self.read_doc(docname)
    ~~~~~~~~~~~~~^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 630, in read_doc
    publisher.publish()
    ~~~~~~~~~~~~~~~~~^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     self.settings)
                                     ^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/io.py", line 106, in read
    self.parse()
    ~~~~~~~~~~^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx/parsers.py", line 85, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
                                 input_source=document['source'])
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ~~~~~~~~~~~~~~~^
        context, state, transitions)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2790, in underline
    self.section(title, source, style, lineno - 1, messages)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
          self.state_machine.input_lines[offset:], input_offset=absoffset,
          node=section_node, match_titles=True)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      node=node, match_titles=match_titles)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ~~~~~~~~~~~~~~~^
        context, state, transitions)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2357, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
                             ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2369, in explicit_construct
    return method(self, expmatch)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2106, in directive
    return self.run_directive(
           ~~~~~~~~~~~~~~~~~~^
        directive_class, match, type_name, option_presets)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2156, in run_directive
    result = directive_instance.run()
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 590, in run
    return self._generate_nodes(prog_name, command, None, nested, commands)
           ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 553, in _generate_nodes
    self._generate_nodes(
    ~~~~~~~~~~~~~~~~~~~~^
        command.name, command, parent=parent, nested=nested
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 528, in _generate_nodes
    for line in lines:
                ^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 361, in _format_command
    for line in _format_usage(ctx):
                ~~~~~~~~~~~~~^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 43, in process_lines
    lines = list(func(ctx))
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 174, in _format_usage
    for line in _get_usage(ctx).splitlines():
                ~~~~~~~~~~^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/sphinx_click/ext.py", line 67, in _get_usage
    pieces = ctx.command.collect_usage_pieces(ctx)
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/click/core.py", line 1012, in collect_usage_pieces
    rv.extend(param.get_usage_pieces(ctx))
              ~~~~~~~~~~~~~~~~~~~~~~^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/click/core.py", line 3104, in get_usage_pieces
    return [self.make_metavar(ctx)]
            ~~~~~~~~~~~~~~~~~^^^^^
  File "/home/feickert/Code/GitHub/scikit-hep/pyhf/.venv/lib/python3.13/site-packages/click/core.py", line 3075, in make_metavar
    var = self.type.get_metavar(param=self, ctx=ctx)
TypeError: DocumentedChoice.get_metavar() got an unexpected keyword argument 'ctx'

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocsDocumentation related

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions