mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
apidoc: Use a template for generating package file
This commit is contained in:
Takeshi KOMIYA
parent
e41d6f3651
commit
b93f53c7e4
@ -114,62 +114,35 @@ def create_module_file(package, basename, opts):
|
|||||||
def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace, excludes=[]): # NOQA
|
def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace, excludes=[]): # NOQA
|
||||||
# type: (str, str, str, List[str], Any, List[str], bool, List[str]) -> None
|
# type: (str, str, str, List[str], Any, List[str], bool, List[str]) -> None
|
||||||
"""Build the text of the file and write the file."""
|
"""Build the text of the file and write the file."""
|
||||||
text = format_heading(1, ('%s package' if not is_namespace else "%s namespace")
|
# build a list of sub packages (directories containing an INITPY file)
|
||||||
% makename(master_package, subroot))
|
subpackages = [sub for sub in subs if not
|
||||||
|
shall_skip(path.join(root, sub, INITPY), opts, excludes)]
|
||||||
if opts.modulefirst and not is_namespace:
|
subpackages = [makename(makename(master_package, subroot), pkgname)
|
||||||
text += format_directive(subroot, master_package)
|
for pkgname in subpackages]
|
||||||
text += '\n'
|
# build a list of sub modules
|
||||||
|
submodules = [path.splitext(sub)[0] for sub in py_files
|
||||||
# build a list of directories that are szvpackages (contain an INITPY file)
|
if not shall_skip(path.join(root, sub), opts, excludes) and
|
||||||
# and also checks the INITPY file is not empty, or there are other python
|
sub != INITPY]
|
||||||
# source files in that folder.
|
submodules = [makename(master_package, makename(subroot, modname))
|
||||||
# (depending on settings - but shall_skip() takes care of that)
|
for modname in submodules]
|
||||||
subs = [sub for sub in subs if not
|
|
||||||
shall_skip(path.join(root, sub, INITPY), opts, excludes)]
|
|
||||||
# if there are some package directories, add a TOC for theses subpackages
|
|
||||||
if subs:
|
|
||||||
text += format_heading(2, 'Subpackages')
|
|
||||||
text += '.. toctree::\n\n'
|
|
||||||
for sub in subs:
|
|
||||||
text += ' %s.%s\n' % (makename(master_package, subroot), sub)
|
|
||||||
text += '\n'
|
|
||||||
|
|
||||||
submods = [path.splitext(sub)[0] for sub in py_files
|
|
||||||
if not shall_skip(path.join(root, sub), opts, excludes) and
|
|
||||||
sub != INITPY]
|
|
||||||
if submods:
|
|
||||||
text += format_heading(2, 'Submodules')
|
|
||||||
if opts.separatemodules:
|
|
||||||
text += '.. toctree::\n\n'
|
|
||||||
for submod in submods:
|
|
||||||
modfile = makename(master_package, makename(subroot, submod))
|
|
||||||
text += ' %s\n' % modfile
|
|
||||||
|
|
||||||
# generate separate file for this module
|
|
||||||
if not opts.noheadings:
|
|
||||||
filetext = format_heading(1, '%s module' % modfile)
|
|
||||||
else:
|
|
||||||
filetext = ''
|
|
||||||
filetext += format_directive(makename(subroot, submod),
|
|
||||||
master_package)
|
|
||||||
write_file(modfile, filetext, opts)
|
|
||||||
else:
|
|
||||||
for submod in submods:
|
|
||||||
modfile = makename(master_package, makename(subroot, submod))
|
|
||||||
if not opts.noheadings:
|
|
||||||
text += format_heading(2, '%s module' % modfile)
|
|
||||||
text += format_directive(makename(subroot, submod),
|
|
||||||
master_package)
|
|
||||||
text += '\n'
|
|
||||||
text += '\n'
|
|
||||||
|
|
||||||
if not opts.modulefirst and not is_namespace:
|
|
||||||
text += format_heading(2, 'Module contents')
|
|
||||||
text += format_directive(subroot, master_package)
|
|
||||||
|
|
||||||
|
context = {
|
||||||
|
'pkgname': makename(master_package, subroot),
|
||||||
|
'subpackages': subpackages,
|
||||||
|
'submodules': submodules,
|
||||||
|
'is_namespace': is_namespace,
|
||||||
|
'modulefirst': opts.modulefirst,
|
||||||
|
'separatemodules': opts.separatemodules,
|
||||||
|
'automodule_options': OPTIONS,
|
||||||
|
'show_headings': not opts.noheadings,
|
||||||
|
}
|
||||||
|
text = ReSTRenderer(template_dir).render('package.rst', context)
|
||||||
write_file(makename(master_package, subroot), text, opts)
|
write_file(makename(master_package, subroot), text, opts)
|
||||||
|
|
||||||
|
if submodules and opts.separatemodules:
|
||||||
|
for submodule in submodules:
|
||||||
|
create_module_file(None, submodule, opts)
|
||||||
|
|
||||||
|
|
||||||
def create_modules_toc_file(modules, opts, name='modules'):
|
def create_modules_toc_file(modules, opts, name='modules'):
|
||||||
# type: (List[str], Any, str) -> None
|
# type: (List[str], Any, str) -> None
|
||||||
|
|||||||
52
sphinx/templates/apidoc/package.rst
Normal file
52
sphinx/templates/apidoc/package.rst
Normal file
@ -0,0 +1,52 @@
|
|||||||
|
{%- macro automodule(modname, options) -%}
|
||||||
|
.. automodule:: {{ modname }}
|
||||||
|
{%- for option in options %}
|
||||||
|
:{{ option }}:
|
||||||
|
{%- endfor %}
|
||||||
|
{%- endmacro %}
|
||||||
|
|
||||||
|
{%- macro toctree(docnames) -%}
|
||||||
|
.. toctree::
|
||||||
|
{% for docname in docnames %}
|
||||||
|
{{ docname }}
|
||||||
|
{%- endfor %}
|
||||||
|
{%- endmacro %}
|
||||||
|
|
||||||
|
{%- if is_namespace %}
|
||||||
|
{{- [pkgname, "namespace"] | join(" ") | e | heading }}
|
||||||
|
{% else %}
|
||||||
|
{{- [pkgname, "package"] | join(" ") | e | heading }}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{%- if modulefirst and not is_namespace %}
|
||||||
|
{{ automodule(pkgname, automodule_options) }}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{%- if subpackages %}
|
||||||
|
Subpackages
|
||||||
|
-----------
|
||||||
|
|
||||||
|
{{ toctree(subpackages) }}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{%- if submodules %}
|
||||||
|
Submodules
|
||||||
|
----------
|
||||||
|
{% if separatemodules %}
|
||||||
|
{{ toctree(submodules) }}
|
||||||
|
{%- else %}
|
||||||
|
{%- for submodule in submodules %}
|
||||||
|
{% if show_headings %}
|
||||||
|
{{- [submodule, "module"] | join(" ") | e | heading(2) }}
|
||||||
|
{% endif %}
|
||||||
|
{{ automodule(submodule, automodule_options) }}
|
||||||
|
{%- endfor %}
|
||||||
|
{% endif %}
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{%- if not modulefirst and not is_namespace %}
|
||||||
|
Module contents
|
||||||
|
---------------
|
||||||
|
|
||||||
|
{{ automodule(pkgname, automodule_options) }}
|
||||||
|
{% endif %}
|
||||||
@ -2,7 +2,6 @@
|
|||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: {{ maxdepth }}
|
:maxdepth: {{ maxdepth }}
|
||||||
|
|
||||||
{% for docname in docnames %}
|
{% for docname in docnames %}
|
||||||
{{ docname }}
|
{{ docname }}
|
||||||
{%- endfor %}
|
{%- endfor %}
|
||||||
|
|||||||
@ -446,3 +446,169 @@ def test_module_file_noheadings(tempdir):
|
|||||||
" :members:\n"
|
" :members:\n"
|
||||||
" :undoc-members:\n"
|
" :undoc-members:\n"
|
||||||
" :show-inheritance:\n")
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
|
||||||
|
def test_package_file(tempdir):
|
||||||
|
outdir = path(tempdir)
|
||||||
|
(outdir / 'testpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / '__init__.py').write_text('')
|
||||||
|
(outdir / 'testpkg' / 'example.py').write_text('')
|
||||||
|
(outdir / 'testpkg' / 'subpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / 'subpkg' / '__init__.py').write_text('')
|
||||||
|
apidoc_main(['-o', tempdir, tempdir / 'testpkg'])
|
||||||
|
assert (outdir / 'testpkg.rst').exists()
|
||||||
|
assert (outdir / 'testpkg.subpkg.rst').exists()
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.rst').text()
|
||||||
|
assert content == ("testpkg package\n"
|
||||||
|
"===============\n"
|
||||||
|
"\n"
|
||||||
|
"Subpackages\n"
|
||||||
|
"-----------\n"
|
||||||
|
"\n"
|
||||||
|
".. toctree::\n"
|
||||||
|
"\n"
|
||||||
|
" testpkg.subpkg\n"
|
||||||
|
"\n"
|
||||||
|
"Submodules\n"
|
||||||
|
"----------\n"
|
||||||
|
"\n"
|
||||||
|
"testpkg.example module\n"
|
||||||
|
"----------------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg.example\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n"
|
||||||
|
"\n"
|
||||||
|
"\n"
|
||||||
|
"Module contents\n"
|
||||||
|
"---------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.subpkg.rst').text()
|
||||||
|
assert content == ("testpkg.subpkg package\n"
|
||||||
|
"======================\n"
|
||||||
|
"\n"
|
||||||
|
"Module contents\n"
|
||||||
|
"---------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg.subpkg\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
|
||||||
|
def test_package_file_separate(tempdir):
|
||||||
|
outdir = path(tempdir)
|
||||||
|
(outdir / 'testpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / '__init__.py').write_text('')
|
||||||
|
(outdir / 'testpkg' / 'example.py').write_text('')
|
||||||
|
apidoc_main(['--separate', '-o', tempdir, tempdir / 'testpkg'])
|
||||||
|
assert (outdir / 'testpkg.rst').exists()
|
||||||
|
assert (outdir / 'testpkg.example.rst').exists()
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.rst').text()
|
||||||
|
assert content == ("testpkg package\n"
|
||||||
|
"===============\n"
|
||||||
|
"\n"
|
||||||
|
"Submodules\n"
|
||||||
|
"----------\n"
|
||||||
|
"\n"
|
||||||
|
".. toctree::\n"
|
||||||
|
"\n"
|
||||||
|
" testpkg.example\n"
|
||||||
|
"\n"
|
||||||
|
"Module contents\n"
|
||||||
|
"---------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.example.rst').text()
|
||||||
|
assert content == ("testpkg.example module\n"
|
||||||
|
"======================\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg.example\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
|
||||||
|
def test_package_file_module_first(tempdir):
|
||||||
|
outdir = path(tempdir)
|
||||||
|
(outdir / 'testpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / '__init__.py').write_text('')
|
||||||
|
(outdir / 'testpkg' / 'example.py').write_text('')
|
||||||
|
apidoc_main(['--module-first', '-o', tempdir, tempdir])
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.rst').text()
|
||||||
|
assert content == ("testpkg package\n"
|
||||||
|
"===============\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n"
|
||||||
|
"\n"
|
||||||
|
"Submodules\n"
|
||||||
|
"----------\n"
|
||||||
|
"\n"
|
||||||
|
"testpkg.example module\n"
|
||||||
|
"----------------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg.example\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n"
|
||||||
|
"\n")
|
||||||
|
|
||||||
|
|
||||||
|
def test_package_file_without_submodules(tempdir):
|
||||||
|
outdir = path(tempdir)
|
||||||
|
(outdir / 'testpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / '__init__.py').write_text('')
|
||||||
|
apidoc_main(['-o', tempdir, tempdir / 'testpkg'])
|
||||||
|
assert (outdir / 'testpkg.rst').exists()
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.rst').text()
|
||||||
|
assert content == ("testpkg package\n"
|
||||||
|
"===============\n"
|
||||||
|
"\n"
|
||||||
|
"Module contents\n"
|
||||||
|
"---------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n")
|
||||||
|
|
||||||
|
|
||||||
|
def test_namespace_package_file(tempdir):
|
||||||
|
outdir = path(tempdir)
|
||||||
|
(outdir / 'testpkg').makedirs()
|
||||||
|
(outdir / 'testpkg' / 'example.py').write_text('')
|
||||||
|
apidoc_main(['--implicit-namespace', '-o', tempdir, tempdir / 'testpkg'])
|
||||||
|
assert (outdir / 'testpkg.rst').exists()
|
||||||
|
|
||||||
|
content = (outdir / 'testpkg.rst').text()
|
||||||
|
assert content == ("testpkg namespace\n"
|
||||||
|
"=================\n"
|
||||||
|
"\n"
|
||||||
|
"Submodules\n"
|
||||||
|
"----------\n"
|
||||||
|
"\n"
|
||||||
|
"testpkg.example module\n"
|
||||||
|
"----------------------\n"
|
||||||
|
"\n"
|
||||||
|
".. automodule:: testpkg.example\n"
|
||||||
|
" :members:\n"
|
||||||
|
" :undoc-members:\n"
|
||||||
|
" :show-inheritance:\n"
|
||||||
|
"\n")
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user