Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 6096c74

Browse files
astrofrogastrofrog
authored
Merge pull request astropy#24 from mhvk/include-all-objects
Allow also non-functions/classes to be included in module API summary.
2 parents c7b46e9 + caf25c9 commit 6096c74

22 files changed

+247
-16
lines changed

‎CHANGES.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ Changes in sphinx-automodapi
66

77
- Fix compatibility with Sphinx 1.6 and 1.7. [#22, #23]
88

9+
- Introduce a new ``:include-all-objects:`` option to ``automodapi`` that will
10+
include not just functions and classes in a module, but also all other
11+
objects. To help this, introduce a new ``:variables-only:`` option for
12+
``automodsumm``. [#24]
13+
914
0.3 (2017-02-20)
1015
----------------
1116

‎sphinx_automodapi/automodapi.py

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@
99
1010
It accepts the following options:
1111
12+
* ``:include-all-objects:``
13+
If present, include not just functions and classes, but all objects.
14+
This includes variables, for which a possible docstring after the
15+
variable definition will be shown.
16+
1217
* ``:no-inheritance-diagram:``
1318
If present, the inheritance diagram will not be shown even if
1419
the module/package has classes.
@@ -121,6 +126,15 @@ class are included in the generated documentation. Defaults to ``False``.
121126
{clsfuncoptions}
122127
"""
123128

129+
automod_templ_vars = """
130+
Variables
131+
{otherhds}
132+
133+
.. automodsumm:: {modname}
134+
:variables-only:
135+
{clsfuncoptions}
136+
"""
137+
124138
automod_templ_inh = """
125139
Class Inheritance Diagram
126140
{clsinhsechds}
@@ -209,6 +223,7 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
209223
inhdiag = maindocstr = top_head = True
210224
hds = '-^'
211225
allowedpkgnms = []
226+
allowothers = False
212227

213228
# look for actual options
214229
unknownops = []
@@ -230,6 +245,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
230245
inherited_members = True
231246
elif opname == 'no-inherited-members':
232247
inherited_members = False
248+
elif opname == 'include-all-objects':
249+
allowothers = True
233250
else:
234251
unknownops.append(opname)
235252

@@ -256,7 +273,8 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
256273
if warnings:
257274
app.warn(msg, location)
258275

259-
ispkg, hascls, hasfuncs = _mod_info(modnm, toskip, onlylocals=onlylocals)
276+
ispkg, hascls, hasfuncs, hasother = _mod_info(
277+
modnm, toskip, onlylocals=onlylocals)
260278

261279
# add automodule directive only if no-main-docstr isn't present
262280
if maindocstr:
@@ -306,6 +324,12 @@ def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
306324
clshds=h2 * 7,
307325
clsfuncoptions=clsfuncoptionstr))
308326

327+
if allowothers and hasother:
328+
newstrs.append(automod_templ_vars.format(
329+
modname=modnm,
330+
otherhds=h2 * 9,
331+
clsfuncoptions=clsfuncoptionstr))
332+
309333
if inhdiag and hascls:
310334
# add inheritance diagram if any classes are in the module
311335
if toskip:
@@ -359,13 +383,15 @@ def _mod_info(modname, toskip=[], onlylocals=True):
359383
it has classes or functions.
360384
"""
361385

362-
hascls = hasfunc = False
386+
hascls = hasfunc = hasother = False
363387

364388
for localnm, fqnm, obj in zip(*find_mod_objs(modname, onlylocals=onlylocals)):
365389
if localnm not in toskip:
366390
hascls = hascls or inspect.isclass(obj)
367391
hasfunc = hasfunc or inspect.isroutine(obj)
368-
if hascls and hasfunc:
392+
hasother = hasother or (not inspect.isclass(obj) and
393+
not inspect.isroutine(obj))
394+
if hascls and hasfunc and hasother:
369395
break
370396

371397
# find_mod_objs has already imported modname
@@ -375,7 +401,7 @@ def _mod_info(modname, toskip=[], onlylocals=True):
375401
ispkg = (hasattr(pkg, '__file__') and isinstance(pkg.__file__, str) and
376402
os.path.split(pkg.__file__)[1].startswith('__init__.py'))
377403

378-
return ispkg, hascls, hasfunc
404+
return ispkg, hascls, hasfunc, hasother
379405

380406

381407
def process_automodapi(app, docname, source):

‎sphinx_automodapi/automodsumm.py

Lines changed: 32 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,18 @@
1616
* ``:classes-only:``
1717
If present, the autosummary table will only contain entries for
1818
classes. This cannot be used at the same time with
19-
``:functions-only:`` .
19+
``:functions-only:`` or ``:variables-only:``.
2020
2121
* ``:functions-only:``
2222
If present, the autosummary table will only contain entries for
2323
functions. This cannot be used at the same time with
24-
``:classes-only:`` .
24+
``:classes-only:`` or ``:variables-only:``.
25+
26+
* ``:variables-only:``
27+
If present, the autosummary table will only contain entries for
28+
variables (everything except functions and classes). This cannot
29+
be used at the same time with ``:classes-only:`` or
30+
``:functions-only:``.
2531
2632
* ``:skip: obj1, [obj2, obj3, ...]``
2733
If present, specifies that the listed objects should be skipped
@@ -107,6 +113,7 @@ class Automodsumm(Autosummary):
107113
option_spec = dict(Autosummary.option_spec)
108114
option_spec['functions-only'] = flag
109115
option_spec['classes-only'] = flag
116+
option_spec['variables-only'] = flag
110117
option_spec['skip'] = _str_list_converter
111118
option_spec['allowed-package-names'] = _str_list_converter
112119
option_spec['inherited-members'] = flag
@@ -131,6 +138,11 @@ def run(self):
131138
# Be sure to respect functions-only and classes-only.
132139
funconly = 'functions-only' in self.options
133140
clsonly = 'classes-only' in self.options
141+
varonly = 'variables-only' in self.options
142+
if [clsonly, funconly, varonly].count(True) > 1:
143+
self.warning('more than one of functions-only, classes-only, '
144+
'or variables-only defined. Ignoring.')
145+
clsonly = funconly = varonly = False
134146

135147
skipnames = []
136148
if 'skip' in self.options:
@@ -144,7 +156,7 @@ def run(self):
144156
'but they were not present. Ignoring.'
145157
.format(objs=option_skipnames, mod=modname))
146158

147-
if funconly and not clsonly:
159+
if funconly:
148160
cont = []
149161
for nm, obj in zip(localnames, objs):
150162
if nm not in skipnames and inspect.isroutine(obj):
@@ -154,10 +166,13 @@ def run(self):
154166
for nm, obj in zip(localnames, objs):
155167
if nm not in skipnames and inspect.isclass(obj):
156168
cont.append(nm)
169+
elif varonly:
170+
cont = []
171+
for nm, obj in zip(localnames, objs):
172+
if nm not in skipnames and not (inspect.isclass(obj) or
173+
inspect.isroutine(obj)):
174+
cont.append(nm)
157175
else:
158-
if clsonly and funconly:
159-
self.warning('functions-only and classes-only both '
160-
'defined. Skipping.')
161176
cont = [nm for nm in localnames if nm not in skipnames]
162177

163178
self.content = cont
@@ -325,27 +340,31 @@ def automodsumm_to_autosummary_lines(fn, app):
325340
opssecs, remainders)):
326341
allindent = i1 + (' ' if i2 is None else i2)
327342

328-
# filter out functions-only and classes-only options if present
343+
# filter out functions-only, classes-only, and ariables-only
344+
# options if present.
329345
oplines = ops.split('\n')
330346
toskip = []
331347
allowedpkgnms = []
332-
funcsonly = clssonly = False
348+
funcsonly = clssonly = varsonly = False
333349
for i, ln in reversed(list(enumerate(oplines))):
334350
if ':functions-only:' in ln:
335351
funcsonly = True
336352
del oplines[i]
337353
if ':classes-only:' in ln:
338354
clssonly = True
339355
del oplines[i]
356+
if ':variables-only:' in ln:
357+
varsonly = True
358+
del oplines[i]
340359
if ':skip:' in ln:
341360
toskip.extend(_str_list_converter(ln.replace(':skip:', '')))
342361
del oplines[i]
343362
if ':allowed-package-names:' in ln:
344363
allowedpkgnms.extend(_str_list_converter(ln.replace(':allowed-package-names:', '')))
345364
del oplines[i]
346-
if funcsonly and clssonly:
347-
msg = ('Defined both functions-only and classes-only options. '
348-
'Skipping this directive.')
365+
if [funcsonly, clssonly, varsonly].count(True) > 1:
366+
msg = ('Defined more than one of functions-only, classes-only, '
367+
'and variables-only. Skipping this directive.')
349368
lnnum = sum([spl[j].count('\n') for j in range(i * 5 + 1)])
350369
app.warn('[automodsumm]' + msg, (fn, lnnum))
351370
continue
@@ -367,6 +386,8 @@ def automodsumm_to_autosummary_lines(fn, app):
367386
continue
368387
if clssonly and not inspect.isclass(obj):
369388
continue
389+
if varsonly and (inspect.isclass(obj) or inspect.isroutine(obj)):
390+
continue
370391
newlines.append(allindent + nm)
371392

372393
# add one newline at the end of the autosummary block

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Documenting a module with classes, functions, and variables that are
2+
imported from other files, and with an inheritance diagram (which then
3+
requires the smart_resolver).

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/input/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module
2+
:include-all-objects:

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Egg.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Egg
2+
===
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autoclass:: Egg
7+
:show-inheritance:
8+
9+
.. rubric:: Attributes Summary
10+
11+
.. autosummary::
12+
13+
~Egg.weight
14+
15+
.. rubric:: Methods Summary
16+
17+
.. autosummary::
18+
19+
~Egg.buy
20+
~Egg.eat
21+
22+
.. rubric:: Attributes Documentation
23+
24+
.. autoattribute:: weight
25+
26+
.. rubric:: Methods Documentation
27+
28+
.. automethod:: buy
29+
.. automethod:: eat

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.FUNNY_WALK_STEPS.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
FUNNY_WALK_STEPS
2+
================
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autodata:: FUNNY_WALK_STEPS

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.PARROT_STATE.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
PARROT_STATE
2+
============
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autodata:: PARROT_STATE

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.Spam.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Spam
2+
====
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autoclass:: Spam
7+
:show-inheritance:

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.add.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
add
2+
===
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autofunction:: add

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/api/sphinx_automodapi.tests.example_module.multiply.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
multiply
2+
========
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module
5+
6+
.. autofunction:: multiply

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodapi

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
2+
sphinx_automodapi.tests.example_module Package
3+
----------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module
6+
7+
Functions
8+
^^^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module
11+
:functions-only:
12+
:toctree: api
13+
14+
Classes
15+
^^^^^^^
16+
17+
.. automodsumm:: sphinx_automodapi.tests.example_module
18+
:classes-only:
19+
:toctree: api
20+
21+
Variables
22+
^^^^^^^^^
23+
24+
.. automodsumm:: sphinx_automodapi.tests.example_module
25+
:variables-only:
26+
:toctree: api
27+
28+
Class Inheritance Diagram
29+
^^^^^^^^^^^^^^^^^^^^^^^^^
30+
31+
.. automod-diagram:: sphinx_automodapi.tests.example_module
32+
:private-bases:
33+
:parts: 1

‎sphinx_automodapi/tests/cases/mixed_toplevel_all_objects/output/index.rst.automodsumm

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
add
7+
multiply
8+
.. currentmodule:: sphinx_automodapi.tests.example_module
9+
10+
.. autosummary::
11+
:toctree: api
12+
13+
Egg
14+
Spam
15+
.. currentmodule:: sphinx_automodapi.tests.example_module
16+
17+
.. autosummary::
18+
:toctree: api
19+
20+
FUNNY_WALK_STEPS
21+
PARROT_STATE

‎sphinx_automodapi/tests/cases/variables/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Documenting a module with global variables

‎sphinx_automodapi/tests/cases/variables/input/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. automodapi:: sphinx_automodapi.tests.example_module.variables
2+
:include-all-objects:

‎sphinx_automodapi/tests/cases/variables/output/api/sphinx_automodapi.tests.example_module.variables.FUNNY_WALK_STEPS.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
FUNNY_WALK_STEPS
2+
================
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.variables
5+
6+
.. autodata:: FUNNY_WALK_STEPS

‎sphinx_automodapi/tests/cases/variables/output/api/sphinx_automodapi.tests.example_module.variables.PARROT_STATE.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
PARROT_STATE
2+
============
3+
4+
.. currentmodule:: sphinx_automodapi.tests.example_module.variables
5+
6+
.. autodata:: PARROT_STATE

‎sphinx_automodapi/tests/cases/variables/output/index.rst.automodapi

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
2+
sphinx_automodapi.tests.example_module.variables Module
3+
-------------------------------------------------------
4+
5+
.. automodule:: sphinx_automodapi.tests.example_module.variables
6+
7+
Variables
8+
^^^^^^^^^
9+
10+
.. automodsumm:: sphinx_automodapi.tests.example_module.variables
11+
:variables-only:
12+
:toctree: api

‎sphinx_automodapi/tests/cases/variables/output/index.rst.automodsumm

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. currentmodule:: sphinx_automodapi.tests.example_module.variables
2+
3+
.. autosummary::
4+
:toctree: api
5+
6+
PARROT_STATE
7+
FUNNY_WALK_STEPS

‎sphinx_automodapi/tests/example_module/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
from .classes import *
22
from .functions import *
3+
from .variables import *

0 commit comments

Comments
 (0)