Question regarding injecting DocStrings

[phil65]

Just trying to understand, from what scope can I insert DocStrings into my project?

This here works:

::: logging.LogRecord

or even:

::: mkdocs.something_from_mkdocs

but

::: ast.AST

(or anything else from ast module) gives "could not collect" error.

EDIT:

My guess would be: because MkDocStrings is using the AST for checking and ast.AST is imported via star operator?
( https://github.com/python/cpython/blob/main/Lib/ast.py#L29C15-L29C15 )

EDIT2:
... and ::: collections.OrderedDict raises a different Exception, jinja2.exceptions.TemplateNotFound: alias.html

[pawamoy]

Hey, that's a very good question! This deserves an entry in the docs 🙂

The ::: ast.AST case does not work, because the AST class is imported from the private _ast module with a wildcard import, as you noted. And since we didn't pre-load the _ast module, or allowed alias resolution to external modules, all the wildcard imported objects are not detected. So when we try to access ast.AST, it fails because there's no AST member in ast. The error is propertly caught.

The collections.OrderedDict case is almost the same, except that this time OrderedDict is imported directly¹, without a wildcard import, so the corresponding alias fail to resolve, ending up with a "template not found alias.html". This error could probably be better handled.

In the end, you can solve this by adding this line to your Python handler options, in mkdocs.yml: preload_modules: [_ast, _collections]. Also, we could consider always resolving to external modules if they are the private equivalent of the source module: if module.thing -> _module.thing then load _module and resolve.

Footnotes

1. Note this import after the class definition:

   try:
       from _collections import OrderedDict
   except ImportError:
       # Leave the pure Python version in place.
       pass
   

   ↩

[phil65]

Okay, thank you for the detailed explanation. The last detail I dont understand: OrderedDict is imported explicitely. Why doesnt it work in that case? Because it´s placed in an exception block and therefore not a direct child of the AST root node?

[pawamoy]

It does not work because it is imported from _collections, which is not loaded.

• collections.OrderedDict points to _collections.OrderedDict
• _collections is not loaded, so collections.OrderedDict cannot be resolved (stays an alias)
• mkdocstrings fails with "no template alias.html"

Let me know if this is still unclear 🙂

[phil65]

One more question if you dont mind, in case you are familiar with the following plugin. 😄
When I am inside a MkDocs-Gen-Files script and I am importing modules there, does that make them "preloaded" for MkDocStrings?

[pawamoy]

If by "importing modules there" you mean import thing or import stuff, then no, the preloading feature has nothing to do with modules being imported or not. By "loaded" we mean "loaded by Griffe", not "loaded by Python". To pre-load a module, you have to use the preload_modules option 🙂 It acts as an include-list. If you want to resolve everything, always, you can use the load_external_modules option, though be careful of the side-effects (explained in the docs).

If by "importing modules there" you mean using the collect method of the handler to manually pre-load things, then yes. But as told above, there's an option for that, that you can use in mkdocs.yml directly.