Allow using sphinx.ext.apidoc as an extension
#12471
Conversation
|
@picnixz note this is still a draft, but perhaps you would like to provide some initial feedback |
chrisjsewell
force-pushed
the
autodoc-auto
branch
3 times, most recently
from
f27dd11 to
dd9615a
Compare
A common usecase, is that users simply want to point sphinx towards a Python module, and have it generate documentation automatically. This is not possible currently, without a "pre-build" step of running the `sphinx-autogen` CLI. This PR adds `sphinx.ext.apidoc` as a sphinx extension, to incorporate the source file generation into the sphinx build.
chrisjsewell
force-pushed
the
autodoc-auto
branch
from
dd9615a to
30ce9b3
Compare
AA-Turner
changed the title
sphinx.ext.apidoc extensionsphinx.ext.apidoc as an extension
| @@ -0,0 +1,10 @@ | |||
| """So program can be started with ``python -m sphinx.apidoc ...``""" | |||
There was a problem hiding this comment.
| """So program can be started with ``python -m sphinx.apidoc ...``""" | |
| """Command-line interface for the apidoc extension.""" |
| from sphinx.locale import __ | ||
| from sphinx.util.console import bold | ||
|
|
||
| from . import WARNING_TYPE, _remove_old_files, create_modules_toc_file, logger, recurse_tree |
There was a problem hiding this comment.
Avoid relative imports:
| from . import WARNING_TYPE, _remove_old_files, create_modules_toc_file, logger, recurse_tree | |
| from sphinx.ext.apidoc import WARNING_TYPE, _remove_old_files, create_modules_toc_file, logger, recurse_tree |
| def main(argv: Sequence[str] = (), /) -> int: | ||
| """Parse and check the command line arguments.""" | ||
| """Run the apidoc CLI.""" |
There was a problem hiding this comment.
Perhaps move main() into __main__.py?
|
|
||
| # destination path should be relative to the source directory | ||
| # TODO account for Windows path? | ||
| if not (destination := _check_string(i, options, 'destination', True)): |
There was a problem hiding this comment.
Lone Booleans at call sites are often hard to interpret -- perhaps make required a keyword-only argument?
| return options[key] | ||
|
|
||
|
|
||
| @dataclass |
There was a problem hiding this comment.
Perhaps?:
| @dataclass | |
| @dataclass(frozen=True) |
I'd also maybe set slots=True, but that is only Python 3.10+
There was a problem hiding this comment.
According to our release plan, we should have dropped 3.9 some months ago so maybe we could first move to 8.x by dropping 3.9 (there are quite a lot of annoying things in between 3.9 and 3.10).
A common use case,
is that users want to simply point sphinx towards a Python module, and have it generate documentation automatically.
(see e.g. readthedocs/readthedocs.org#1139)
This is not possible currently,
without a "pre-build" step of running the
sphinx-apidocCLI.(and in fact there are numerous examples of users calling
sphinx-apidocwithin theirconf.pyto work around this)This PR adds
sphinx.ext.apidocas a sphinx extension, to incorporate the source file generation into the sphinx build in a "formal" manner, using the API rather than the CLI.related to #6829 (but does not close it)
This PR is currently in draft, since there are a number of TODOs in the code, and documentation needs to be added.