show_source displaying absolute paths when publishing

[cpvannier]

Hi,

Thank you for this project!

I have an issue with the show_source option with mkdocstrings for Python.

When I turn the option on and build my documentation locally with mkdocs serve in my myproject/ repository, it works fine and displays like this:

some_function()
Docstring of the function.
Source code in mypackage/module.py

However, when I try to publish my documentation, using mkdocs gh-deploy --config-file ../myproject/mkdocs.yml --remote-branch main from my myproject.github.io/ repository, the paths become absolute:

some_function()
Docstring of the function.
Source code in /home/user/Documents/myproject/mypackage/module.py

Is this a bug or am I missing something?

Thanks in advance

[pawamoy]

Hi!

When showing the source, we compute the path to the file relatively to the current working directory. So when you serve from within your project, it works fine, but when you deploy from another project, the relative path cannot be computed anymore, and the absolute path is used instead.

The next version of MkDocs comes with the ability to specify a path as relative to the config file (or docs dir, or current page), so we should then be able to add an option to Griffe to specify the base path using this. Relative paths will then always be computed relatively to this base path.

In the meantime, if you're willing to override templates (which I don't really recommend doing until we have proper Jinja blocks), you can change relative_filepath to relative_package_filepath in the templates showing source code.

% git grep relative_filepath
src/mkdocstrings_handlers/python/templates/material/_base/class.html:            <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
src/mkdocstrings_handlers/python/templates/material/_base/class.html:          <summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
src/mkdocstrings_handlers/python/templates/material/_base/function.html:        <summary>Source code in <code>{{ function.relative_filepath }}</code></summary>

This will give more consistent results, but will drop any folder above the Python package (like src, typically).

[cpvannier]

Thanks for the quick reply!

If you don't recommend doing this, I guess I have no other option but to wait for the next versions of mkdocs and mkdocstrings, and remove the absolute path from the deployed documentation manually in the meantime.

Thank you, and keep up the good work 🙏

[pawamoy]

By the way we do have Jinja blocks now. Docs are not yet super great though: https://mkdocstrings.github.io/python/usage/customization/#templates.

[pawamoy]

We now automatically switch to the relative package path if the relative path itself is absolute, see #622.