IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

apidoc: Miscellaneous refactoring

Browse Source
This commit is contained in:
Adam Turner 2025-01-07 07:26:37 +00:00
parent 47599df1bc
commit d1b49a12ef
1 changed files with 31 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
sphinx/ext/apidoc.py
View File

@ -19,7 +19,6 @@ import os
import os.path import os.path
import re import re
import sys import sys
from copy import copy
from importlib.machinery import EXTENSION_SUFFIXES from importlib.machinery import EXTENSION_SUFFIXES
from pathlib import Path from pathlib import Path
from typing import TYPE_CHECKING, Any, Protocol from typing import TYPE_CHECKING, Any, Protocol
@ -48,7 +47,7 @@ else:
'show-inheritance', 'show-inheritance',
} }
PY_SUFFIXES = ('.py', '.pyx', *tuple(EXTENSION_SUFFIXES)) PY_SUFFIXES = ('.py', '.pyx', *EXTENSION_SUFFIXES)
template_dir = os.path.join(package_dir, 'templates', 'apidoc') template_dir = os.path.join(package_dir, 'templates', 'apidoc')
@ -386,7 +385,7 @@ Note: By default this script will not overwrite already created files."""),
'--version', '--version',
action='version', action='version',
dest='show_version', dest='show_version',
version='%%(prog)s %s' % __display_version__, version=f'%(prog)s {__display_version__}',
) )
parser.add_argument('module_path', help=__('path to module to document')) parser.add_argument('module_path', help=__('path to module to document'))
@ -576,15 +575,15 @@ Note: By default this script will not overwrite already created files."""),
metavar='EXTENSIONS', metavar='EXTENSIONS',
dest='extensions', dest='extensions',
action='append', action='append',
help=__('enable arbitrary extensions'), help=__('enable arbitrary extensions, used when --full is given'),
) )
for ext in EXTENSIONS: for ext in EXTENSIONS:
group.add_argument( group.add_argument(
'--ext-%s' % ext, f'--ext-{ext}',
action='append_const', action='append_const',
const='sphinx.ext.%s' % ext, const=f'sphinx.ext.{ext}',
dest='extensions', dest='extensions',
help=__('enable %s extension') % ext, help=__('enable %s extension, used when --full is given') % ext,
) )
group = parser.add_argument_group(__('Project templating')) group = parser.add_argument_group(__('Project templating'))
@ -618,19 +617,22 @@ class CliOptions(Protocol):
implicit_namespaces: bool implicit_namespaces: bool
automodule_options: set[str] automodule_options: set[str]
suffix: str suffix: str
remove_old: bool
# --full only
full: bool full: bool
append_syspath: bool append_syspath: bool
header: str | None header: str
author: str | None author: str | None
version: str | None version: str | None
release: str | None release: str | None
extensions: list[str] | None extensions: list[str] | None
templatedir: str | None templatedir: str | None
remove_old: bool
def main(argv: Sequence[str] = (), /) -> int: def main(argv: Sequence[str] = (), /) -> int:
"""Parse and check the command line arguments.""" """Run the apidoc CLI."""
locale.setlocale(locale.LC_ALL, '') locale.setlocale(locale.LC_ALL, '')
sphinx.locale.init_console() sphinx.locale.init_console()
@ -669,7 +671,7 @@ def main(argv: Sequence[str] = (), /) -> int:
if module.startswith(prev_module + '.'): if module.startswith(prev_module + '.'):
continue continue
prev_module = module prev_module = module
text += ' %s\n' % module text += f' {module}\n'
d: dict[str, Any] = { d: dict[str, Any] = {
'path': args.destdir, 'path': args.destdir,
'sep': False, 'sep': False,
@ -715,8 +717,17 @@ def main(argv: Sequence[str] = (), /) -> int:
) )
if args.remove_old and not args.dryrun: if args.remove_old and not args.dryrun:
for existing in Path(args.destdir).glob(f'**/*.{args.suffix}'): _remove_old_files(written_files, Path(args.destdir), args.suffix)
if existing not in written_files:
return 0
def _remove_old_files(
written_files: Sequence[Path], destdir: Path, suffix: str
) -> None:
files_to_keep = frozenset(written_files)
for existing in destdir.rglob(f'*.{suffix}'):
if existing not in files_to_keep:
try: try:
existing.unlink() existing.unlink()
except OSError as exc: except OSError as exc:
@ -727,8 +738,6 @@ def main(argv: Sequence[str] = (), /) -> int:
type='autodoc', type='autodoc',
) )
return 0
# So program can be started with "python -m sphinx.apidoc ..." # So program can be started with "python -m sphinx.apidoc ..."
if __name__ == '__main__': if __name__ == '__main__':