Skip Alias Resolution

[chrimaho]

When I write a new module, with Python docstrings (in Google style), I want to render these docstrings on my docs page. This is typical. However, the challenge is in the resolution of Aliases through Griffe. Specifically, Griffe forces the loading and resolution of every single module which I am importing in to my script; even if those imported docs are not even necessary for my documentation.

Let me give you an example:

import pandas as pd
import numpy as np

def my_fancy_func():
    """
    Some documentation in Google style
    """
    return pd.DataFrame({'a': [1, 2, 3], 'b': ['a', 'b', 'c']})

In the above scenario, we have one module which imports two libraries: pandas and numpy, and one super simple function with basic documentation.

Now, when I try to load this documentation using the command:

mkdocs serve

I receive a HUGE and super complicated error:

(.venv) name@MACHINE:/path-to-dir$ mkdocs serve
INFO    -  DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
             File "/path-to-dir/.venv/lib/python3.10/site-packages/mike/mkdocs_plugin.py", line 6, in <module>
               from pkg_resources import iter_entry_points
             File "/path-to-dir/.venv/lib/python3.10/site-packages/pkg_resources/__init__.py", line 118, in <module>
               warnings.warn(
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  DeprecationWarning: invalid escape sequence '\_'
             File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/agents/visitor.py", line 177, in get_module
               top_node = compile(self.code, mode="exec", filename=str(self.filepath), flags=ast.PyCF_ONLY_AST, optimize=1)
             File "/path-to-dir/.venv/lib/python3.10/site-packages/pyspark/pandas/supported_api_gen.py", line 355, in
               return func_str[:-1] + "\_"  # noqa: W605
ERROR   -  Error reading page 'docs/code/processing_times.md': Could not resolve alias src.databricks_helpers.processing_times.pd pointing at pandas (in
           src/databricks_helpers/processing_times.py:5)
Traceback (most recent call last):
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1116, in _resolve_target
    resolved = self.modules_collection.get_member(self.target_path)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/mixins.py", line 77, in get_member
    return self.members[parts[0]]  # type: ignore[attr-defined]
KeyError: 'pandas'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/path-to-dir/.venv/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/path-to-dir/.venv/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/path-to-dir/.venv/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 86, in serve
    builder(config)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 322, in build
    _populate_page(file.page, config, files, dirty)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 175, in _populate_page
    page.render(config, files)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocs/structure/pages.py", line 271, in render
    self.content = md.convert(self.markdown)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/markdown/core.py", line 254, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "/path-to-dir/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 84, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/path-to-dir/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 99, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/path-to-dir/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 117, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings/extension.py", line 125, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings/extension.py", line 221, in _process_block
    rendered = handler.render(data, options)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/handler.py", line 338, in render
    return template.render(
  File "/path-to-dir/.venv/lib/python3.10/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/path-to-dir/.venv/lib/python3.10/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/module.html", line 1, in top-level template code
    {% extends "_base/module.html" %}
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 55, in top-level template code
    {% block contents scoped %}
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 62, in block 'contents'
    {% block children scoped %}
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 65, in block 'children'
    {% include "children.html" with context %}
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/children.html", line 1, in top-level template code
    {% extends "_base/children.html" %}
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/children.html", line 110, in top-level template code
    {% for child in obj.all_members
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/rendering.py", line 184, in do_order_members
    return sorted(members, key=order_map[order])
  File "/path-to-dir/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/rendering.py", line 40, in _sort_key_source
    return item.lineno if item.lineno is not None else -1
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 816, in lineno
    return self.final_target.lineno
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1092, in final_target
    target = target.target  # type: ignore[assignment]
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1064, in target
    self.resolve_target()
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1110, in resolve_target
    self._resolve_target()
  File "/path-to-dir/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1118, in _resolve_target
    raise AliasResolutionError(self) from error
griffe.exceptions.AliasResolutionError: Could not resolve alias src.databricks_helpers.processing_times.pd pointing at pandas (in src/databricks_helpers/processing_times.py:5)

Which confuses me a lot. Why is my rendering failing because it's pointing at Pandas?

Through a LOT of searching through your documentation, I finally found how to resolve it. I needed to list pandas in the preload_modules section on the mkdocs.yml config file.

Like this:

plugins:
  - autorefs
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            allow_inspection: true
            docstring_style: google
            docstring_options:
              replace_admonitions: no
            show_root_heading: true
            show_root_toc_entry: false
            show_root_full_path: true
            show_source: true
            show_object_full_path: false
            show_signature_annotations: true
            show_category_heading: true
            show_if_no_docstring: true
            heading_level: 3
            members_order: source
            group_by_category: false
            paths:
              - src/databricks_helpers
            preload_modules:
              - __future__
              - typeguard
              - datetime
              - pandas
            filters:
              - "!^__all__"

Now, what happens when I do mkdocs serve, is that it takes over 2 minutes to load the docs eeeeeevery single time I save my files, which greatly reduces my efficiency in building my docs. The reason for this is that mkdocstrings-python will re-load every single module listed in preload_modules every single time one of the underlying files changes listed in paths. And because Pandas takes sooooooo long to load (that's a separate issue from this one), then therefore these mkdocstrings processes will also take so long to load them.

But I question why this is even necessary? The pandas package is not necessary for my docs rendering at all. It's needed for Unit Testing, that's fine. But not for docs rendering... So why does it even need to be preloaded? It's so that Griffe will be to render the Alias Resolution, right? But I don't want it to. I just want to build my docs quickly and easily.

Therefore, I'd like to recommend an additional option here to skip the Alias resolution process in Griffe. Therefore, I do not need to add my additional packages in this preload_modules section.

One other use case to consider is in packages that are not even loaded in to my local virtual environment. One such example is the DBUtils package, necessary for various processes on DataBricks environment. But when coding on my local PC, this pacakage is not installable, because it's only available in DataBricks workspace. But I need to include the import statement in my modules because when that package is run on DataBricks later, then that dbutils package will be available. However, as soon as I add this import statement to my script, then Griffe will expect to preload it... but it's not installed... so therefore Griffe will not allow my docs to even be rendered. But the challenge is, I don't even need DBUtils for my docs?? So therefore, I'd like to skip this Alias Resolution part alltogether.

Please help me with this one.

Here's my package versions:

• Griffe: griffe 0.36.2
• MkDocs: mkdocs 1.5.3
• MkDocs-Material: mkdocs-material 9.4.2
• MkDocStrings: mkdocstrings 0.23.0
• MkDocStrings-Python: mkdocstrings-python 1.7.0

Thank you.

[pawamoy]

Hello, thanks for report, and sorry for the trouble. Is your repository public so I could take a look?

[chrimaho]

Apologies, it's on a private repo.

Don't get me wrong, I love the package! And it makes code documentation super easy. Thanks! Just trying to help make it a little bit smoother overall 😉

[pawamoy]

Of course, no worries 🙂

OK, then a first guess: if your package is stored in the src folder, then your paths are wrong, they should be paths: [src]. Docs: https://mkdocstrings.github.io/python/usage/#using-the-paths-option.
Could you try that, also removing the preload_modules option, and run the command again in verbose mode (mkdocs serve -v or mkdocs build -v) and paste the logs, redacting any sensitive information?

[chrimaho]

Sure thing, here you go 👇

Directory Structure

Structure

├── .venv
├── ...
├── docs
│   ├── assets
│   │   ├── css
│   │   └── ...
│   ├── docs
│   │   ├── code
│   │   │   ├── defaults.md
│   │   │   ├── index.md
│   │   │   └── processing_times.md
│   │   └── usage
│   │       └── overview.md
│   ├── overrides
│   │   ├── home.html
│   │   └── main.html
│   └── index.md
├── src
│   ├── databricks_helpers
│   │   ├── defaults.py
│   │   └── processing_times.py
│   └── tests
│       ├── test_defaults.py
│       └── test_processing_times.py
├── ...
├── .mkdocs.yml
└── README.md

File Contents

defaults.pd

from __future__ import annotations
from distutils.util import strtobool
from typing import Any
from typeguard import typechecked

class Defaults:
    """
    Docstrings
    """
    ...

processing_times.py

from datetime import datetime
import pandas as pd
from pyspark.sql import (
    SparkSession,
    functions as F,
)
from typeguard import typechecked

def capture_processing_times():
    """
    Docstrings
    """
    ...

defaults.md

::: src.databricks_helpers.defaults

processing_times.md

::: src.databricks_helpers.processing_times

mkdocs.yml

site_name: DataBricks Toolbox
site_description: Helper files/functions/classes for generic DataBricks processes.
site_author: "[MY NAME](mailto:MY_EMAIL)"
site_dir: web
repo_name: REPO_NAME
repo_url: REPO_URL
edit_uri: -/edit/main/docs/

theme:
  name: material
  favicon: assets/icons/databricks.png
  coverpage_icon: assets/icons/databricks.png
  custom_dir: docs/overrides
  palette:
    primary: teal
    accent: indigo
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.indexes
    - navigation.top
    - navigation.instant
    - search.highlight
    - search.suggest
    - toc.follow
    - content.action.edit
    - content.action.view
    - content.code.annotate
  logo: assets/icons/databricks.png
  icon:
    repo: material/gitlab
    edit: material/file-edit-outline
    view: material/file-eye-outline

nav:
  - Home: index.md
  - Usage:
      - Overview: docs/usage/overview.md
  - Code:
      - docs/code/index.md
      - Defaults: docs/code/defaults.md
      - Processing Times: docs/code/processing_times.md

markdown_extensions:
  - admonition
  - meta
  - attr_list
  - md_in_html
  - toc:
      permalink: "🔗"
  - pymdownx.emoji
  - pymdownx.magiclink
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.progressbar
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

extra:
  version:
    provider: mike
    default: latest

extra_css:
  - assets/css/style.css
  - assets/css/admonitions.css
  - assets/css/code_chunks.css
  - https://site-assets.fontawesome.com/releases/v6.4.2/css/all.css

plugins:
  - search:
      lang: en
  - autorefs
  - mike:
      version_selector: true
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            allow_inspection: true
            docstring_style: google
            docstring_options:
              replace_admonitions: no
            show_root_heading: true
            show_root_toc_entry: false
            show_root_full_path: true
            show_source: true
            show_object_full_path: false
            show_signature_annotations: true
            show_category_heading: true
            show_if_no_docstring: true
            heading_level: 3
            members_order: source
            group_by_category: false
            paths:
              - src
            # preload_modules:
            #   - __future__
            #   - distutils
            #   - typing
            #   - typeguard
            #   - datetime
            #   - pandas
            #   - pyspark.sql
            filters:
              - "!^__all__"

Error Message

Detailed error message

(.venv) name@MACHINE:path-to-dir/repo$ mkdocs serve -v
DEBUG   -  Loading configuration file: path-to-dir/repo/mkdocs.yml
DEBUG   -  Loaded theme configuration for 'material' from '/path-to-dir/repo/.venv/lib/python3.10/site-packages/material/templates/mkdocs_theme.yml': {'language': 'en', 'direction': None, 'features': [], 'font': {'text': 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png', 'static_templates': ['404.html']}
INFO    -  DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
             File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mike/mkdocs_plugin.py", line 6, in <module>
               from pkg_resources import iter_entry_points
             File "path-to-dir/repo/.venv/lib/python3.10/site-packages/pkg_resources/__init__.py", line 118, in <module>
               warnings.warn(
DEBUG   -  Config value 'config_file_path' = 'path-to-dir/repo/mkdocs.yml'
DEBUG   -  Config value 'site_name' = 'DataBricks Toolbox'
DEBUG   -  Config value 'nav' = [{'Home': 'index.md'}, {'Usage': [{'Overview': 'docs/usage/overview.md'}]}, {'Code': ['docs/code/index.md', {'Defaults': 'docs/code/defaults.md'}, {'Processing Times': 'docs/code/processing_times.md'}]}]
DEBUG   -  Config value 'pages' = None
DEBUG   -  Config value 'exclude_docs' = None
DEBUG   -  Config value 'not_in_nav' = None
DEBUG   -  Config value 'site_url' = None
DEBUG   -  Config value 'site_description' = 'Helper files/functions/classes for generic DataBricks processes.'
DEBUG   -  Config value 'site_author' = '[MY NAME](mailto:EMAIL_ADDRESS)'
DEBUG   -  Config value 'theme' = Theme(name='material', dirs=['path-to-dir/repo/docs/overrides', 'path-to-dir/repo/.venv/lib/python3.10/site-packages/material/templates', '/path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/templates'], static_templates={'sitemap.xml', '404.html'}, name='material', locale=Locale('en'), language='en', direction=None, features=['navigation.tabs', 'navigation.tabs.sticky', 'navigation.sections', 'navigation.expand', 'navigation.indexes', 'navigation.top', 'navigation.instant', 'search.highlight', 'search.suggest', 'toc.follow', 'content.action.edit', 'content.action.view', 'content.code.annotate'], font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon={'repo': 'material/gitlab', 'edit': 'material/file-edit-outline', 'view': 'material/file-eye-outline'}, favicon='assets/icons/databricks.png', coverpage_icon='assets/icons/databricks.png', palette={'primary': 'teal', 'accent': 'indigo'}, logo='assets/icons/databricks.png')
DEBUG   -  Config value 'docs_dir' = 'path-to-dir/repo/docs'
DEBUG   -  Config value 'site_dir' = '/tmp/mkdocs_smoitg42'
DEBUG   -  Config value 'copyright' = None
DEBUG   -  Config value 'google_analytics' = None
DEBUG   -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG   -  Config value 'use_directory_urls' = True
DEBUG   -  Config value 'repo_url' = 'REPO-URL'
DEBUG   -  Config value 'repo_name' = 'repo'
DEBUG   -  Config value 'edit_uri_template' = None
DEBUG   -  Config value 'edit_uri' = '-/edit/main/docs/'
DEBUG   -  Config value 'extra_css' = ['assets/css/style.css', 'assets/css/admonitions.css', 'assets/css/code_chunks.css', 'https://site-assets.fontawesome.com/releases/v6.4.2/css/all.css']
DEBUG   -  Config value 'extra_javascript' = []
DEBUG   -  Config value 'extra_templates' = []
DEBUG   -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'admonition', 'meta', 'attr_list', 'md_in_html', 'pymdownx.emoji', 'pymdownx.magiclink', 'pymdownx.details', 'pymdownx.superfences', 'pymdownx.progressbar', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.tabbed', 'pymdownx.tasklist', 'pymdownx.arithmatex']
DEBUG   -  Config value 'mdx_configs' = {'toc': {'permalink': '🔗'}, 'pymdownx.snippets': {'check_paths': True}, 'pymdownx.tabbed': {'alternate_style': True}, 'pymdownx.tasklist': {'custom_checkbox': True}, 'pymdownx.arithmatex': {'generic': True}, 'pymdownx.emoji': {'emoji_index': <function twemoji at 0x7f7a2cec5090>, 'emoji_generator': <function to_svg at 0x7f7a2cec5240>}}
DEBUG   -  Config value 'strict' = False
DEBUG   -  Config value 'remote_branch' = 'gh-pages'
DEBUG   -  Config value 'remote_name' = 'origin'
DEBUG   -  Config value 'extra' = {'version': {'provider': 'mike', 'default': 'latest'}}
DEBUG   -  Config value 'plugins' = {'material/search': <material.plugins.search.plugin.SearchPlugin object at 0x7f7a2c44c460>, 'autorefs': <mkdocs_autorefs.plugin.AutorefsPlugin object at 0x7f7a2c44d030>, 'mike': <mike.mkdocs_plugin.MikePlugin object at 0x7f7a2c29ba00>, 'mkdocstrings': <mkdocstrings.plugin.MkdocstringsPlugin object at 0x7f7a2c305930>}
DEBUG   -  Config value 'hooks' = {}
DEBUG   -  Config value 'watch' = []
DEBUG   -  Config value 'validation' = {'nav': {'omitted_files': 20, 'not_found': 30, 'absolute_links': 20}, 'links': {'not_found': 30, 'absolute_links': 20, 'unrecognized_links': 20}}
DEBUG   -  Running 1 `startup` events
INFO    -  Building documentation...
DEBUG   -  Running 4 `config` events
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/docs/overrides/locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/docs/overrides/locales'
DEBUG   -  mkdocs_autorefs: Adding AutorefsExtension to the list
DEBUG   -  mkdocstrings: Adding extension to the list
DEBUG   -  mkdocstrings: Picked up existing autorefs instance <mkdocs_autorefs.plugin.AutorefsPlugin object at 0x7f7a2c44d030>
INFO    -  Cleaning site directory
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/.venv/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  No translations found here: 'path-to-dir/repo/docs/overrides/locales'
DEBUG   -  Running 1 `files` events
DEBUG   -  Reading markdown pages.
DEBUG   -  Reading: index.md
DEBUG   -  Running 1 `page_markdown` events
DEBUG   -  Running 1 `page_content` events
DEBUG   -  mkdocs_autorefs: Mapping identifiers to URLs for page index.md
DEBUG   -  Reading: docs/code/index.md
DEBUG   -  Running 1 `page_markdown` events
INFO    -  Doc file 'docs/code/index.md' contains an unrecognized relative link './defaults', it was left as is. Did you mean 'defaults.md'?
DEBUG   -  Running 1 `page_content` events
DEBUG   -  mkdocs_autorefs: Mapping identifiers to URLs for page docs/code/index.md
DEBUG   -  Reading: docs/code/defaults.md
DEBUG   -  Running 1 `page_markdown` events
DEBUG   -  Running 1 `page_content` events
DEBUG   -  mkdocs_autorefs: Mapping identifiers to URLs for page docs/code/defaults.md
DEBUG   -  Reading: docs/code/processing_times.md
DEBUG   -  Running 1 `page_markdown` events
DEBUG   -  mkdocstrings: Matched '::: src.databricks_helpers.processing_times'
DEBUG   -  mkdocstrings: Using handler 'python'
DEBUG   -  mkdocstrings: Collecting data
DEBUG   -  griffe: Found src: loading
DEBUG   -  griffe: Loading path [PosixPath('src'), PosixPath('path-to-dir/repo/src')]
DEBUG   -  griffe: Skip path-to-dir/repo/src/databricks_helpers/defaults.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/databricks_helpers/processing_times.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/databricks_helpers/version.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/databricks_helpers/__init__.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/tests/setup.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/tests/test_defaults.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/tests/test_version.py, another module took precedence
DEBUG   -  griffe: Skip path-to-dir/repo/src/tests/__init__.py, another module took precedence
DEBUG   -  griffe: Loading path src/databricks_helpers/__init__.py
DEBUG   -  griffe: Loading path src/tests/__init__.py
DEBUG   -  griffe: Loading path src/databricks_helpers/defaults.py
DEBUG   -  griffe: Loading path src/databricks_helpers/processing_times.py
DEBUG   -  griffe: Loading path src/databricks_helpers/version.py
DEBUG   -  griffe: Loading path src/tests/setup.py
DEBUG   -  griffe: Loading path src/tests/test_defaults.py
DEBUG   -  griffe: Loading path src/tests/test_version.py
DEBUG   -  griffe: Iteration 1 finished, 0 aliases resolved, still 0 to go
DEBUG   -  mkdocstrings: Updating handler's rendering env
DEBUG   -  mkdocstrings: Rendering templates
DEBUG   -  mkdocstrings: python/templates/material/module.html: Rendering src.databricks_helpers.processing_times
DEBUG   -  mkdocstrings: python/templates/material/children.html: Rendering children of src.databricks_helpers.processing_times
ERROR   -  Error reading page 'docs/code/processing_times.md': Could not resolve alias src.databricks_helpers.processing_times.datetime pointing at datetime.datetime (in src/databricks_helpers/processing_times.py:2)
Traceback (most recent call last):
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1116, in _resolve_target
    resolved = self.modules_collection.get_member(self.target_path)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/mixins.py", line 78, in get_member
    return self.members[parts[0]].get_member(parts[1:])  # type: ignore[attr-defined]
KeyError: 'datetime'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "path-to-dir/repo/.venv/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 86, in serve
    builder(config)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 322, in build
    _populate_page(file.page, config, files, dirty)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 175, in _populate_page
    page.render(config, files)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocs/structure/pages.py", line 271, in render
    self.content = md.convert(self.markdown)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/markdown/core.py", line 254, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 84, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 99, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/markdown/blockparser.py", line 117, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings/extension.py", line 125, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings/extension.py", line 221, in _process_block
    rendered = handler.render(data, options)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/handler.py", line 338, in render
    return template.render(
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/module.html", line 1, in top-level template code
    {% extends "_base/module.html" %}
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 55, in top-level template code
    {% block contents scoped %}
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 62, in block 'contents'
    {% block children scoped %}
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/module.html", line 65, in block 'children'
    {% include "children.html" with context %}
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/children.html", line 1, in top-level template code
    {% extends "_base/children.html" %}
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/templates/material/_base/children.html", line 110, in top-level template code
    {% for child in obj.all_members
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/rendering.py", line 184, in do_order_members
    return sorted(members, key=order_map[order])
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/mkdocstrings_handlers/python/rendering.py", line 40, in _sort_key_source
    return item.lineno if item.lineno is not None else -1
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 816, in lineno
    return self.final_target.lineno
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1092, in final_target
    target = target.target  # type: ignore[assignment]
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1064, in target
    self.resolve_target()
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1110, in resolve_target
    self._resolve_target()
  File "path-to-dir/repo/.venv/lib/python3.10/site-packages/griffe/dataclasses.py", line 1118, in _resolve_target
    raise AliasResolutionError(self) from error
griffe.exceptions.AliasResolutionError: Could not resolve alias src.databricks_helpers.processing_times.datetime pointing at datetime.datetime (in src/databricks_helpers/processing_times.py:2)

[pawamoy]

That's perfect, thanks a lot!

I was able to reproduce and find the issues 🙂

First, a thing that I should fix in mkdocstrings-python: when ordering from source, accessing unresolved aliases' lineno attribute triggered an alias resolution error. We should catch it and return alias_lineno instead.

Second, a few things that you should fix in your configuration:

The paths option is actually a global-only option and therefore must appear under python, not options:

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [src]

Since the paths option was in the wrong location, it had no effect, and Griffe couldn't find the package. It was then falling back on inspection (trying to import the module), which also failed since it was not installed and therefore not available in sys.path.

Also, your package is databricks_helpers, not src, so in your Markdown file you must use ::: databricks_helpers.defaults, not ::: src.databricks_helpers.defaults.

---

Thanks again for the useful info!

[chrimaho]

Hey @pawamoy, Thank you so much!!

Yes, that has fixed it now.

I have:

1. Upgraded to the latest version of mkdocstrings-python
2. Changed my mkdocs.yml to have the same structure you showed above ☝️
3. Changed the import lines on my *.md files to not include the src. part at the front, just like you mentioned.

Then, when I run mkdocs serve, it will build everything is able to build successfully! 👍

No more checking for Alias Resolution errors, no more needing to pre-loading modules, no more wating 2+ minutes for my docs to render every time I save my files. This third one isn't your issue, it's an issue in Pandas; but I still found it super frustrating.

Now I don't! Thanks! 😁

[pawamoy]

Happy to hear everything is working fine now! Thanks for letting me know 😄