#mkdocstrings — Public Fediverse posts

Shout out to everybody at #QuansightLabs for nominating #mkdocstrings for the first round of OSS funding! ❤️❤️❤️ Their fund initiative is mentioned in their 2024 annual report: https://labs.quansight.org/blog/labs-annual-report-2024

#python #oss #funding

I released both TypeScript and C handler for #mkdocstrings to the public. My time is limited, my knowledge of these languages too, and these handlers are experimental, so I decided to make them public, hoping they'll get traction and contributions from people experienced in these languages 🙂

- https://mkdocstrings.github.io/typescript/
- https://mkdocstrings.github.io/c/

#python #mkdocs

After a long period of refactors, bug fixes, docs and general support, I will now focus on adding features to #mkdocstrings 🙂

The latest two Insiders features:

- backlinks! https://mkdocstrings.github.io/python/usage/configuration/general/#backlinks
- "public" filtering method: https://mkdocstrings.github.io/python/usage/configuration/members/#filters

Coming up next:

- (insiders) ordering according to `__all__`: https://github.com/mkdocstrings/python/issues/219
- (insiders) fine-grain configuration: https://github.com/mkdocstrings/mkdocstrings/issues/658
- support unpacking `Unpack[TypedDict]` in signatures: https://github.com/mkdocstrings/python/issues/207

I'm really close to releasing the backlinks feature of mkdocs-autorefs/mkdocstrings.

I'm just working on merging this performance optimization in Python-Markdown first, because otherwise build time can increase a lot: https://github.com/Python-Markdown/markdown/pull/1510.

#python #pythonmarkdown #mkdocs #mkdocstrings

Damn. Seem to have run into a problem that means that #mkdocstrings isn't being shown off as well as it should be: https://github.com/mkdocstrings/mkdocstrings/discussions/742

I'm seeing more and more users adding configuration options that do not exist to their #mkdocstrings config. I suppose they come from #LLMs 🤷

New Insiders feature coming soon in #mkdocstrings: automatic backlinks!

Amazing experience combined with Material for MkDocs instant previews 🚀

Example in Pydantic's docs:

mkdocstrings-python can now format signatures and attribute values with Ruff, so you don't need to depend on Black anymore if you prefer Ruff 🙂

It spawns a subprocess each time, but Ruff is so fast that I didn't see any perf hit. Later, when Ruff has official (or at least non-experimental third-party) Python bindings, we can refactor to avoid spawning subprocesses.

#black #ruff #mkdocstrings

mkdocstrings users, how would you feel if the Python handler started depending on Pydantic? The goal is to improve data validation (configuration options) as well as error reporting, and ease maintenance of JSON schemas (linting in IDEs like VSCode).

#python #mkdocstrings #pydantic

mkdocstrings now has a dedicated Discord server, for those of you who prefer this platform 😄

https://discord.gg/uPh9mmS8

#mkdocstrings

And now the #mkdocstrings handlers projects and features! First, the mkdocstrings-shell handler, which lets you inject documentation for shell scripts or shell libraries:

https://mkdocstrings.github.io/shell/

I just released relative-crossrefs and scoped-crossrefs for the #Python handler of #mkdocstrings 😮 (sponsors only)

https://mkdocstrings.github.io/python/usage/configuration/docstrings/#relative_crossrefs

@vitaut @bert_hubert wow, how come I only learn now about this #mkdocstrings handler :D

Any #Jinja experts over here? When debugging #mkdocstrings, #Python frames often report the wrong line number in Jinja templates. Calling `warnings.warn` from a template also starts reporting frames from the parent template, not the current one 🤔 Any idea why?

More details here: https://github.com/pallets/jinja/discussions/1971

Super excited about the possible outcomes of this request: https://github.com/pallets/jinja/issues/1967 -> to preserve #Jinja comment in the AST when parsing sources.

This would allow extracting documentation from sources directly, to automatically render API docs for Jinja templates (for example with a #mkdocstrings Jinja handler).

Docs closer to the sources for better readability and maintainability 🙂

...aaaaaand one more feature for #mkdocstrings-#python: on-the-fly modernization of type annotations 🏄

Even if you're stuck using typing.Optional, typing.Union, typing.List, etc., this option will transform these into their more modern equivalent when rendering your docs.

For example:

Optional[Union[int, List[int]]]

...becomes:

int | list[int] | None

Docs: https://mkdocstrings.github.io/python/usage/configuration/signatures/#modernize_annotations

New feature in the #Python handler of #mkdocstrings: class inheritance diagrams with Mermaid 🎩

- docs: https://mkdocstrings.github.io/python/usage/configuration/general/#show_inheritance_diagram
- live example: https://mkdocstrings.github.io/griffe/reference/griffe/#griffe.Class (sorry, heavy page)

Phew, just pushed a first prototype of a #TypeScript handler for #mkdocstrings 🥵

If you are part of Insiders and are interested in trying it out, you can find some instructions here: https://github.com/mkdocstrings/mkdocstrings/issues/636#issuecomment-1999841858

I just switched #mkdocstrings to my #Copier #uv template. It now uses uv instead of #PDM.

Since dependency resolution and installation is much faster, I don't even bother grouping dependencies by use (docs, tests, etc.), and install everything in each CI job.

Since it's faster, I've also removed the limit on the maximum number of parallel jobs (previously it was set to 4).

Result: CI runs 4x faster (around 2min instead of 8min). Neat 🙂

https://github.com/mkdocstrings/mkdocstrings/actions

#Griffe (Insiders) just got a new feature: expressions modernization.

It will allow downstream tools like #mkdocstrings to render type annotations compatible with older Python versions, as if they were using latest features of the #Python language.

Typically:

- typing.Union[int, str] becomes int | str
- typing.Optional[int] becomes int | None
- typing.Set[int] becomes set[int]
- etc.

https://mkdocstrings.github.io/griffe/expressions/#modernization

New feature for the #Python handler of #mkdocstrings: parameter headings!

Enabling headings for parameters will give each one of them:

- a permalink (great for pointing users to the param docs)
- a ToC entry
- an objects inventory entry

These two entries allow cross-references from internal and external pages 🚀

See the docs here: https://mkdocstrings.github.io/python/usage/configuration/headings/#parameter_headings

Next Insiders feature in the #Python handler for #mkdocstrings: permalinks on function/method parameters! Each parameter will get a permalink, an entry in the table of contents, and an entry in the generated objects inventory, allowing cross-references.

To manually cross-link, the syntax will be `[link to param][path.to.function(param)]`.

Please comment on the suggested syntax here: https://github.com/mkdocstrings/mkdocstrings/issues/640

ToC preview:

2024 starts well with the first funding goal reached for #mkdocstrings and more generally my Insiders projects! 🚀

The dashboard on GitHub sponsors is the source of truth, so I'll wait for it to actually mark the goal as reached before releasing some features into the community versions 🙂

I'll start merging right now anyway, but expect a few days delay before seeing new versions.

https://pawamoy.github.io/insiders/#500-plasmavac-user-guide

Big thanks to #RStudio for sponsoring me and funding #mkdocstrings!

We're approchaing the $500/month funding goal for #mkdocstrings (and more generally all my Insiders projects).

The funding goal is called "PlasmaVac User Guide" so, which one of these PlasmaVac would you like to get for christmas 😂 🎄 ?

Done with #midjourney 🤖

#FastAPI now has proper API docs 🎉 They are built with #mkdocstrings and a #Griffe extension for PEP 727. The PEP was written by @tiangolo himself!

The PR to add API docs to #python-#markdown was merged 🎉 72 files changed, +2K/-1K loc, quite a PR! https://github.com/Python-Markdown/markdown/pull/1379

Too bad the docs deploy job failed 😅 Will update and add the link once the docs are up 🙂

Also, it means we'll be able to load Python-Markdown's inventory and cross-reference its API!

With #mkdocstrings:

The #Python handler of #mkdocstrings now supports rendering function signature overloads. It stacks them up vertically (see screenshots).