diff --git a/CHANGES b/CHANGES index a90602d9d..1319812cf 100644 --- a/CHANGES +++ b/CHANGES @@ -44,6 +44,7 @@ Deprecated * ``sphinx.environment.NoUri`` * ``sphinx.ext.apidoc.format_directive()`` * ``sphinx.ext.apidoc.format_heading()`` +* ``sphinx.ext.apidoc.makename()`` * ``sphinx.ext.autodoc.importer.MockFinder`` * ``sphinx.ext.autodoc.importer.MockLoader`` * ``sphinx.ext.autodoc.importer.mock()`` diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 2ecb1e2e7..569e0a3d9 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -171,6 +171,11 @@ The following is a list of deprecated interfaces. - 4.0 - N/A + * - ``sphinx.ext.apidoc.makename()`` + - 2.1 + - 4.0 + - ``sphinx.ext.apidoc.module_join()`` + * - ``sphinx.ext.autodoc.importer.MockFinder`` - 2.1 - 4.0 diff --git a/sphinx/ext/apidoc.py b/sphinx/ext/apidoc.py index 2243e0644..2ec337d4c 100644 --- a/sphinx/ext/apidoc.py +++ b/sphinx/ext/apidoc.py @@ -56,6 +56,8 @@ template_dir = path.join(package_dir, 'templates', 'apidoc') def makename(package, module): # type: (str, str) -> str """Join package and module with a dot.""" + warnings.warn('makename() is deprecated.', + RemovedInSphinx40Warning) # Both package and module can be None/empty. if package: name = package @@ -66,6 +68,12 @@ def makename(package, module): return name +def module_join(*modnames): + # type: (*str) -> str + """Join module names with dots.""" + return '.'.join(filter(None, modnames)) + + def write_file(name, text, opts): # type: (str, str, Any) -> None """Write the output file for module/package .""" @@ -97,7 +105,7 @@ def format_directive(module, package=None): """Create the automodule directive and add the options.""" warnings.warn('format_directive() is deprecated.', RemovedInSphinx40Warning) - directive = '.. automodule:: %s\n' % makename(package, module) + directive = '.. automodule:: %s\n' % module_join(package, module) for option in OPTIONS: directive += ' :%s:\n' % option return directive @@ -106,7 +114,7 @@ def format_directive(module, package=None): def create_module_file(package, basename, opts): # type: (str, str, Any) -> None """Build the text of the file and write the file.""" - qualname = makename(package, basename) + qualname = module_join(package, basename) context = { 'show_headings': not opts.noheadings, 'basename': basename, @@ -123,17 +131,18 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_ # build a list of sub packages (directories containing an INITPY file) subpackages = [sub for sub in subs if not shall_skip(path.join(root, sub, INITPY), opts, excludes)] - subpackages = [makename(makename(master_package, subroot), pkgname) + subpackages = [module_join(master_package, subroot, pkgname) for pkgname in subpackages] # build a list of sub modules submodules = [path.splitext(sub)[0] for sub in py_files if not shall_skip(path.join(root, sub), opts, excludes) and sub != INITPY] - submodules = [makename(master_package, makename(subroot, modname)) + submodules = [module_join(master_package, subroot, modname) for modname in submodules] + pkgname = module_join(master_package, subroot) context = { - 'pkgname': makename(master_package, subroot), + 'pkgname': pkgname, 'subpackages': subpackages, 'submodules': submodules, 'is_namespace': is_namespace, @@ -143,7 +152,7 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_ 'show_headings': not opts.noheadings, } text = ReSTRenderer(template_dir).render('package.rst', context) - write_file(makename(master_package, subroot), text, opts) + write_file(pkgname, text, opts) if submodules and opts.separatemodules: for submodule in submodules: @@ -250,7 +259,7 @@ def recurse_tree(rootpath, excludes, opts): if not is_namespace or len(py_files) > 0: create_package_file(root, root_package, subpackage, py_files, opts, subs, is_namespace, excludes) - toplevels.append(makename(root_package, subpackage)) + toplevels.append(module_join(root_package, subpackage)) else: # if we are at the root level, we don't require it to be a package assert root == rootpath and root_package is None