Migrate docs to mkdocs

[PLangowski]

No description provided.

[miczyg1]

Comparing the overall look and feel

Before:

After:

In my opinion it looks so much worse...

It was @macpijan idea/request to migrate to mkdocs: #5 (comment) so maybe he can review as well.

[PLangowski]

@miczyg1 I agree, it's much less readable.

[PLangowski]

@macpijan Have you looked at this?

[pietrushnic]

@macpijan we would like to have the release by the end of the week. We would appreciate your review and opinion about mkdocs vs sphinix. I would also prefer mkdocs, but the question is how to make it look reasonable.

[miczyg1]

@miczyg1 I agree, it's much less readable.

Have you researched alternative themes or mkdocs @PLangowski ?

[PLangowski]

@miczyg1 mkdocs has 2 built-in themes: mkdocs (the one we don't like) and readthedocs.

readdthedocs looks like this:

Still not great, but better than the previous one IMO.

If we don't choose this, then I'm afraid we will have to look for/create our own custom theme.

[miczyg1]

Still not great, but better than the previous one IMO.

Much better than the previous one.

If we don't choose this, then I'm afraid we will have to look for/create our own custom theme.

I guess we will have to stick with this. Unless @macpijan will retract with his request to migrate to mkdocs.

[macpijan]

@PLangowski Please link issue to PR if you work on one. I assume it's this one: Dasharo/dasharo-issues#451

If you go through it's content, the readthedocs template is explicitly mentioned, so I am not sure why we are discovering it again.

I would stick to this if we had done the migration work already.

[PLangowski]

@macpijan @miczyg1
I set the theme https://github.com/Dasharo/Openness-Score/compare/4de394b7acabd9dfdaba0fa834a8efb046074aef..273e11322ef9316d3b1985e6951572f7d0dd4bdf#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2R3

[miczyg1]

@PLangowski Please link issue to PR if you work on one. I assume it's this one: Dasharo/dasharo-issues#451

If you go through it's content, the readthedocs template is explicitly mentioned, so I am not sure why we are discovering it again.

I would stick to this if we had done the migration work already.

Thanks for clarifying @macpijan

Now that I look on mkdocstrings parsers, Sphinx style has the poorest support: https://mkdocstrings.github.io/griffe/reference/docstrings/#parsers-features
Besides the minimal migration we done just to use mkdocs, the docstrings should have been rewritten too, into Numpy or Google style, to have some reasonable quality compared to what we had with Sphinx. It just shows that the analysis of the requirement was not done well enough. I must say I am not satisfied with the looks of mkdocs still... And it seems it can be made better. @PLangowski

[PLangowski]

@miczyg1
I see. Since we want to publish a minor release tomorrow, I don't think we have time to rewrite the docstrings now. I see two options here:

• Add this "partial" migration to the minor release
• Skip this and prepare a full migration for a full release (v0.2)

Either way, we can plan a full migration for v0.2, the question is whether what we did here should appear in v0.1.1.

[miczyg1]

@miczyg1 I see. Since we want to publish a minor release tomorrow, I don't think we have time to rewrite the docstrings now. I see two options here:

• Add this "partial" migration to the minor release
• Skip this and prepare a full migration for a full release (v0.2)

Either way, we can plan a full migration for v0.2, the question is whether what we did here should appear in v0.1.1.

I don't know how much time do you have left but I still don't think I can sign-off the mkdocs migration in its current state. To me it is incomplete. I can merge this PR, but the mkdocs migration will not be finished IMO.

@pietrushnic cc