def automodsumm_to_autosummary_lines(fn, app):
"""
Generates lines from a file with an "automodsumm" entry suitable for
feeding into "autosummary".
Searches the provided file for `automodsumm` directives and returns
a list of lines specifying the `autosummary` commands for the modules
requested. This does *not* return the whole file contents - just an
autosummary section in place of any :automodsumm: entries. Note that
any options given for `automodsumm` are also included in the
generated `autosummary` section.
Parameters
----------
fn : str
The name of the file to search for `automodsumm` entries.
app : sphinx.application.Application
The sphinx Application object
Return
------
lines : list of str
Lines for all `automodsumm` entries with the entries replaced by
`autosummary` and the module's members added.
"""
import os
from inspect import isfunction, isclass
fullfn = os.path.join(app.builder.env.srcdir, fn)
with open(fullfn) as fr:
if 'astropy.sphinx.ext.automodapi' in app._extensions:
from astropy.sphinx.ext.automodapi import automodapi_replace
# Must do the automodapi on the source to get the automodsumm
# that might be in there
filestr = automodapi_replace(fr.read(), app, True, fn, False)
else:
filestr = fr.read()
spl = _automodsummrex.split(filestr)
#0th entry is the stuff before the first automodsumm line
indent1s = spl[1::5]
mods = spl[2::5]
opssecs = spl[3::5]
indent2s = spl[4::5]
remainders = spl[5::5]
# only grab automodsumm sections and convert them to autosummary with the
# entries for all the public objects
newlines = []
#loop over all automodsumms in this document
for i, (i1, i2, modnm, ops, rem) in enumerate(zip(indent1s, indent2s, mods,
opssecs, remainders)):
allindent = i1 + i2
#filter out functions-only and classes-only options if present
oplines = ops.split('\n')
toskip = []
funcsonly = clssonly = False
for i, ln in reversed(list(enumerate(oplines))):
if ':functions-only:' in ln:
funcsonly = True
del oplines[i]
if ':classes-only:' in ln:
clssonly = True
del oplines[i]
if ':skip:' in ln:
toskip.extend(_str_list_converter(ln.replace(':skip:', '')))
del oplines[i]
if funcsonly and clssonly:
msg = ('Defined both functions-only and classes-only options. '
'Skipping this directive.')
lnnum = sum([spl[j].count('\n') for j in range(i * 5 + 1)])
app.warn('[automodsumm]' + msg, (fn, lnnum))
continue
newlines.append(i1 + '.. autosummary::')
newlines.extend(oplines)
for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=True)):
if nm in toskip:
continue
if funcsonly and not isfunction(obj):
continue
if clssonly and not isclass(obj):
continue
newlines.append(allindent + '~' + fqn)
return newlines
def automodsumm_to_autosummary_lines(fn, app):
"""
Generates lines from a file with an "automodsumm" entry suitable for
feeding into "autosummary".
Searches the provided file for `automodsumm` directives and returns
a list of lines specifying the `autosummary` commands for the modules
requested. This does *not* return the whole file contents - just an
autosummary section in place of any :automodsumm: entries. Note that
any options given for `automodsumm` are also included in the
generated `autosummary` section.
Parameters
----------
fn : str
The name of the file to search for `automodsumm` entries.
app : sphinx.application.Application
The sphinx Application object
Return
------
lines : list of str
Lines for all `automodsumm` entries with the entries replaced by
`autosummary` and the module's members added.
"""
fullfn = os.path.join(app.builder.env.srcdir, fn)
with open(fullfn) as fr:
if 'astropy.sphinx.ext.automodapi' in app._extensions:
from astropy.sphinx.ext.automodapi import automodapi_replace
# Must do the automodapi on the source to get the automodsumm
# that might be in there
filestr = automodapi_replace(fr.read(), app, True, fn, False)
else:
filestr = fr.read()
spl = _automodsummrex.split(filestr)
#0th entry is the stuff before the first automodsumm line
indent1s = spl[1::5]
mods = spl[2::5]
opssecs = spl[3::5]
indent2s = spl[4::5]
remainders = spl[5::5]
# only grab automodsumm sections and convert them to autosummary with the
# entries for all the public objects
newlines = []
#loop over all automodsumms in this document
for i, (i1, i2, modnm, ops, rem) in enumerate(
zip(indent1s, indent2s, mods, opssecs, remainders)):
allindent = i1 + i2
#filter out functions-only and classes-only options if present
oplines = ops.split('\n')
toskip = []
funcsonly = clssonly = False
for i, ln in reversed(list(enumerate(oplines))):
if ':functions-only:' in ln:
funcsonly = True
del oplines[i]
if ':classes-only:' in ln:
clssonly = True
del oplines[i]
if ':skip:' in ln:
toskip.extend(_str_list_converter(ln.replace(':skip:', '')))
del oplines[i]
if funcsonly and clssonly:
msg = ('Defined both functions-only and classes-only options. '
'Skipping this directive.')
lnnum = sum([spl[j].count('\n') for j in range(i * 5 + 1)])
app.warn('[automodsumm]' + msg, (fn, lnnum))
continue
newlines.append(i1 + '.. autosummary::')
newlines.extend(oplines)
for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=True)):
if nm in toskip:
continue
if funcsonly and not inspect.isfunction(obj):
continue
if clssonly and not inspect.isclass(obj):
continue
newlines.append(allindent + '~' + fqn)
return newlines
def automodsumm_to_autosummary_lines(fn, app):
"""
Generates lines from a file with an "automodsumm" entry suitable for
feeding into "autosummary".
Searches the provided file for `automodsumm` directives and returns
a list of lines specifying the `autosummary` commands for the modules
requested. This does *not* return the whole file contents - just an
autosummary section in place of any :automodsumm: entries. Note that
any options given for `automodsumm` are also included in the
generated `autosummary` section.
Parameters
----------
fn : str
The name of the file to search for `automodsumm` entries.
app : sphinx.application.Application
The sphinx Application object
Return
------
lines : list of str
Lines for all `automodsumm` entries with the entries replaced by
`autosummary` and the module's members added.
"""
fullfn = os.path.join(app.builder.env.srcdir, fn)
with open(fullfn) as fr:
if "astropy.sphinx.ext.automodapi" in app._extensions:
from astropy.sphinx.ext.automodapi import automodapi_replace
# Must do the automodapi on the source to get the automodsumm
# that might be in there
filestr = automodapi_replace(fr.read(), app, True, fn, False)
else:
filestr = fr.read()
spl = _automodsummrex.split(filestr)
# 0th entry is the stuff before the first automodsumm line
indent1s = spl[1::5]
mods = spl[2::5]
opssecs = spl[3::5]
indent2s = spl[4::5]
remainders = spl[5::5]
# only grab automodsumm sections and convert them to autosummary with the
# entries for all the public objects
newlines = []
# loop over all automodsumms in this document
for i, (i1, i2, modnm, ops, rem) in enumerate(zip(indent1s, indent2s, mods, opssecs, remainders)):
allindent = i1 + ("" if i2 is None else i2)
# filter out functions-only and classes-only options if present
oplines = ops.split("\n")
toskip = []
allowedpkgnms = []
funcsonly = clssonly = False
for i, ln in reversed(list(enumerate(oplines))):
if ":functions-only:" in ln:
funcsonly = True
del oplines[i]
if ":classes-only:" in ln:
clssonly = True
del oplines[i]
if ":skip:" in ln:
toskip.extend(_str_list_converter(ln.replace(":skip:", "")))
del oplines[i]
if ":allowed-package-names:" in ln:
allowedpkgnms.extend(_str_list_converter(ln.replace(":allowed-package-names:", "")))
del oplines[i]
if funcsonly and clssonly:
msg = "Defined both functions-only and classes-only options. " "Skipping this directive."
lnnum = sum([spl[j].count("\n") for j in range(i * 5 + 1)])
app.warn("[automodsumm]" + msg, (fn, lnnum))
continue
# Use the currentmodule directive so we can just put the local names
# in the autosummary table. Note that this doesn't always seem to
# actually "take" in Sphinx's eyes, so in `Automodsumm.run`, we have to
# force it internally, as well.
newlines.extend([i1 + ".. currentmodule:: " + modnm, "", ".. autosummary::"])
newlines.extend(oplines)
ols = True if len(allowedpkgnms) == 0 else allowedpkgnms
for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=ols)):
if nm in toskip:
continue
if funcsonly and not inspect.isfunction(obj):
continue
if clssonly and not inspect.isclass(obj):
continue
newlines.append(allindent + nm)
return newlines
