sphinx.ext.apidoc does not include header in modules.rst

[djhoese]

Describe the bug

The new sphinx.ext.apidoc extension does not have an option equivalent to --project of the CLI which becomes "header" in the code. The main issue with this is that this option is used to give the title of the modules.rst file that is generated by default. Without it being set, the default "", leads to no page title in modules.rst. This means that the modules.rst page not only has no title, but the title can't be overwritten in an external toctree (ex. My API <api/modules>).

Part of the confusion comes from "header" or "--project" being documented as for the "--full" case only, but it isn't.

How to Reproduce

index.rst:

My Docs
=======

.. toctree::
    :maxdepth: 1

    My API <api/modules>

conf.py:

# sphinx.ext.apidoc was added to sphinx in 8.2.0
needs_sphinx = "8.2.0"

extensions = ["sphinx.ext.autodoc", "sphinx.ext.apidoc"]

# API docs
apidoc_modules = [
    {
        "path": "../../satpy",
        "destination": "api/",
    },
]
apidoc_separate_modules = True
apidoc_include_private = True

Environment Information

Platform:              linux; (Linux-6.9.3-76060903-generic-x86_64-with-glibc2.35)
Python version:        3.12.8 | packaged by conda-forge | (main, Dec  5 2024, 14:24:40) [GCC 13.3.0])
Python implementation: CPython
Sphinx version:        8.2.1
Docutils version:      0.21.2
Jinja2 version:        3.1.5
Pygments version:      2.18.0

Sphinx extensions

["sphinx.ext.autodoc", "sphinx.ext.apidoc"]

Additional context

The header is passed here:

sphinx/sphinx/ext/apidoc/_generate.py

Lines 193 to 197 in 44346bb

	context = {
	'header': opts.header,
	'maxdepth': opts.max_depth,
	'docnames': modules,
	}

And used in the template here:

sphinx/sphinx/templates/apidoc/toc.rst.jinja

Line 1 in 44346bb

{{ header | heading }}

But is defined in code as --full only along with the actual documentation for the apidoc cli tool:

sphinx/sphinx/ext/apidoc/_shared.py

Lines 61 to 69 in 44346bb

	# --full only
	full: bool = False
	append_syspath: bool = False
	header: str = ''
	author: str | None = None
	version: str | None = None
	release: str | None = None
	extensions: Sequence[str] | None = None
	template_dir: str | None = None

[AA-Turner]

Happy to accept a PR.

A

[djhoese]

For the comment record, the PR is #13391

[AA-Turner]

Sphinx 8.2.2 has been released.

A