|
205 | 205 |
|
206 | 206 | # replaces pending_xref node with desc_type for type annotations |
207 | 207 | sphinx.domains.python.type_to_xref = lambda t, e=None: addnodes.desc_type("", nodes.Text(t)) |
| 208 | + |
| 209 | +# -- Autosummary patch to get list of a classes, funcs automatically ---------- |
| 210 | + |
| 211 | +from importlib import import_module |
| 212 | +from inspect import getmembers, isclass, isfunction |
| 213 | +import sphinx.ext.autosummary |
| 214 | +from sphinx.ext.autosummary import Autosummary |
| 215 | +from docutils.parsers.rst import directives |
| 216 | +from docutils.statemachine import StringList |
| 217 | + |
| 218 | + |
| 219 | +class BetterAutosummary(Autosummary): |
| 220 | + """Autosummary with autolisting for modules. |
| 221 | +
|
| 222 | + By default it tries to import all public names (__all__), |
| 223 | + otherwise import all classes and/or functions in a module. |
| 224 | +
|
| 225 | + Options: |
| 226 | + - :autolist: option to get list of classes and functions from currentmodule. |
| 227 | + - :autolist-classes: option to get list of classes from currentmodule. |
| 228 | + - :autolist-functions: option to get list of functions from currentmodule. |
| 229 | +
|
| 230 | + Example Usage: |
| 231 | +
|
| 232 | + .. currentmodule:: ignite.metrics |
| 233 | +
|
| 234 | + .. autosummary:: |
| 235 | + :nosignatures: |
| 236 | + :autolist: |
| 237 | + """ |
| 238 | + |
| 239 | + # Add new option |
| 240 | + _option_spec = Autosummary.option_spec.copy() |
| 241 | + _option_spec.update( |
| 242 | + { |
| 243 | + "autolist": directives.unchanged, |
| 244 | + "autolist-classes": directives.unchanged, |
| 245 | + "autolist-functions": directives.unchanged, |
| 246 | + } |
| 247 | + ) |
| 248 | + option_spec = _option_spec |
| 249 | + |
| 250 | + def run(self): |
| 251 | + for auto in ("autolist", "autolist-classes", "autolist-functions"): |
| 252 | + if auto in self.options: |
| 253 | + # Get current module name |
| 254 | + module_name = self.env.ref_context.get("py:module") |
| 255 | + # Import module |
| 256 | + module = import_module(module_name) |
| 257 | + |
| 258 | + # Get public names (if possible) |
| 259 | + try: |
| 260 | + names = getattr(module, "__all__") |
| 261 | + except AttributeError: |
| 262 | + # Get classes defined in the module |
| 263 | + cls_names = [ |
| 264 | + name[0] |
| 265 | + for name in getmembers(module, isclass) |
| 266 | + if name[-1].__module__ == module_name and not (name[0].startswith("_")) |
| 267 | + ] |
| 268 | + # Get functions defined in the module |
| 269 | + fn_names = [ |
| 270 | + name[0] |
| 271 | + for name in getmembers(module, isfunction) |
| 272 | + if (name[-1].__module__ == module_name) and not (name[0].startswith("_")) |
| 273 | + ] |
| 274 | + names = cls_names + fn_names |
| 275 | + # It may happen that module doesn't have any defined class or func |
| 276 | + if not names: |
| 277 | + names = [name[0] for name in getmembers(module)] |
| 278 | + |
| 279 | + if auto == "autolist": |
| 280 | + # Get list of all classes and functions inside module |
| 281 | + names = [ |
| 282 | + name for name in names if (isclass(getattr(module, name)) or isfunction(getattr(module, name))) |
| 283 | + ] |
| 284 | + else: |
| 285 | + if auto == "autolist-classes": |
| 286 | + # Get only classes |
| 287 | + check = isclass |
| 288 | + elif auto == "autolist-functions": |
| 289 | + # Get only functions |
| 290 | + check = isfunction |
| 291 | + else: |
| 292 | + raise NotImplementedError |
| 293 | + |
| 294 | + names = [name for name in names if check(getattr(module, name))] |
| 295 | + |
| 296 | + # Update content |
| 297 | + self.content = StringList(names) |
| 298 | + return super().run() |
| 299 | + |
| 300 | + |
| 301 | +# Patch original Autosummary |
| 302 | +sphinx.ext.autosummary.Autosummary = BetterAutosummary |
0 commit comments