Skip to content

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

@matthewfeickert

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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions