docs: Format markdown documents

[gabyx]

Description

Format all markdown docs with prettier.

Reason for the Change

• All markdown documents should be formatted. I choose normally prettier because there is no better easier tool out there which works nicely. It adheres to CommonMark etc. Ok there is pandoc and other formatters. We can discuss that in BPA for language guidlines on docs maybe.

[cmdoret]

A markdown formatter woudl indeed be nice to have, but how about using mdformat instead?

I'm suggesting it for the following reasons:

• it has a pre-commit config, so we could just add it to .pre-commit-config.yaml
• it is in python, so we can add it to our poetry docs dependency group
• It is also CommonMark-compliant

They have a readme section on why using mdformat instead of prettier. What do you think?

[gabyx]

@cmdoret : haha, I went already on this journey, I would not recommend mdformat, I tried it in the past, the docs about prettier having troubles is outdated. I used prettier always in my toolchains and never had any trouble. Prettier is at version 3.3 etc and pretty heavily maintained. Although I look for some dedicated/fast tool to format commonmark (pandoc etc. is another beast but to wide-scoped).
So I can just say its stable and works and should support commonmark. Also it is more actively backed by sponsors etc. So no I am 100% not sold on using it.

About the .precommit jeah if you use a python environment, it might give you something stable. But I would not rely on this. Markdown formatting has nothing to do with python itself. So just putting it in the toolchain of python is an easy selling point but jeah. Formatting should be later on be a CI task, stable, pinned and containerized etc.

My suggestion is Githooks, run the formatting in containerized (docker, podman, nix compatible) shared hooks, everywhere , use it in CI as well with some setup..., have it stable.
I would not focus for now on the CI formatting
I could prepare a PR which tries to accomplish to let you give a feel what the benefits are.
If you want to stick to .precommit, for now, all good, I am just a bit worried how it runs on CI, how stable that is etc? Or better I dont understand the .precommit action :), how does it work? it will use a python env and run all hooks with that, if yes this is sluggish and not nice, I d rather vote for something more stable.

[cmdoret]

I see, 👍 for prettier then (as long as it's containerized).

pre-commit is not meant to run on CI: it is only used to setup git pre-commit hooks on the developer's machine. All pre-commit does is automating installation of the hook scripts in .git/.

All good for GitHooks, I have no preference, as long as it automates actions on git commits.

[gabyx]

@cmdoret : Ahh ok, so you dont run it on CI, because you actually can do that =) (its probably a subscription model, payed lol). But dont do that lol.
Jeah, I know how .pre-commit works =), Githooks is written by me, I know all the shittyness of Git hooks and their niceities etc.

Software Best Practice Goal for every project I wanna drive further is: CI runs exaclty the same as you run locally, no excuses ;) (beeing pragmatic here, ok minimal differences are allowed, but not with version pinning etc., I have enough painful experiences with these topics lol)
CI is ground truth. Tools like Git hooks are nice! but if used they MUST align with CI 100%, so jeah Githooks can do that.
I would like however to include a Nix feature in Githooks too, such that we do not need nested container feature.

[cmdoret]

✔️ for the prettier setup, we can figure out pre-commit / ci separately

[almutlue]

Thanks for this @cmdoret, @gabyx! I'm sorry for being late to the discussion. It looks like we are running into rendering issues for our docs when using prettier (see here). I thought that prettier and sphinx would work with each other, but maybe not all the extensions we use (e.g. myst parser)? I did not directly find a good explanation when googling. What do you think we should do? Rollback and scope prettier to markdowns outside docs?

[almutlue]

It is also a bit disappointing that our checks did not catch this - it is true that the docs are technically building, but still a warning would have been nice 😞

[gabyx]

Oh, yes thats wos dumb. Good that you checked.

May be we should ignore the prettier in the sphynx doc etc.

[gabyx]

It is also a bit disappointing that our checks did not catch this - it is true that the docs are technically building, but still a warning would have been nice 😞

I think it cannot, markdown is pretty agnostic thats also good, (not like latex where you get shitty errors) so it will render but corrupted... it is how it is =). Or what checks to you relate to?