Skip to content

More mkdocs options#45

Open
damskii9992 wants to merge 3 commits into
masterfrom
add_doc_inventories
Open

More mkdocs options#45
damskii9992 wants to merge 3 commits into
masterfrom
add_doc_inventories

Conversation

@damskii9992

Copy link
Copy Markdown
Contributor

This PR adds more quality-of-life stuff to the documentation:

Relative_crossrefs and scoped_crossrefs allows links within docstrings to other methods, like [name][.method] will provide a link within the docs to the method .method of the class, see https://mkdocstrings.github.io/python/usage/configuration/docstrings/#scoped_crossrefs
for information on how to use it.

I also add a filter which is the default filter minus repr and dir since i assume we don't want those methods in our api-reference.

Lastly i add inventories to numpy and scipp. This allows mkdocs to provide links to these libraries whenever their types are encountered and it allows easy references like [array][scipp.array] in the documentation.

@damskii9992 damskii9992 added [scope] enhancement Adds/improves features (major.MINOR.patch) [priority] medium Normal/default priority labels Jun 11, 2026
inventories:
- url: https://scipp.github.io/objects.inv
- url: https://numpy.org/doc/stable/objects.inv
- url: https://easyscience.github.io/core/2.3.1/objects.inv

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we avoid pinning the core inventory to 2.3.1 here? Since NumPy uses stable and Scipp exposes an unversioned inventory, the core URL should ideally be something like https://easyscience.github.io/core/latest/objects.inv once core publishes that alias.

It may also be worth adding a pixi.toml docs task in core to build and verify objects.inv.

@damskii9992 damskii9992 Jun 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can solve this issue by changing the alias-type of mike. You've currently set it to "redirect" in the pixi.toml command, using "symlink" or "copy" should make it work (i think). According to Claude, symlinks aren't treated well by github pages though, so maybe we need to use "copy" for this to work . . .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[priority] medium Normal/default priority [scope] enhancement Adds/improves features (major.MINOR.patch)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants