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