Second draft for contribution guide

[tlunet]

Continuing #248 ...

I've tried a solution that would allow to write the main repo documentation (README, CHANGELOG, ...) in markdown on the repos, with links to other pages (e.g for CONTRIBUTING.mg) and automatically convert them into rst files and build the documentation from it.

Main idea of the last commits is to solve #250

[codecov]

Codecov Report

Base: 68.47% // Head: 68.50% // Increases project coverage by +0.02% 🎉

Coverage data is based on head (eee723c) compared to base (eadf81c).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #257      +/-   ##
==========================================
+ Coverage   68.47%   68.50%   +0.02%     
==========================================
  Files         226      226              
  Lines       19510    19510              
==========================================
+ Hits        13360    13365       +5     
+ Misses       6150     6145       -5     

Impacted Files	Coverage Δ
...SDC/implementations/sweeper_classes/Runge_Kutta.py	97.40% <ø> (ø)
pySDC/projects/soft_failure/generate_statistics.py	75.37% <0.00%> (+0.50%)	⬆️
...mentations/problem_classes/Van_der_Pol_implicit.py	98.36% <0.00%> (+1.63%)	⬆️
...C/projects/soft_failure/implicit_sweeper_faults.py	96.52% <0.00%> (+2.08%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[pancetta]

Uh, this sounds great! Pro tip: if you want to check what your PR does to the website, wait for the CI to finish and have a look at the artifacts. In docs you can see how the website will look like.

[tlunet]

Uh, this sounds great! Pro tip: if you want to check what your PR does to the website, wait for the CI to finish and have a look at the artifacts. In docs you can see how the website will look like.

Thanks ! I did compile locally the website like this :

./docs/update_apidocs.sh
cd docs
make html

which allows me to test already this relative links etc ... (just the plot and generated images from project where missing). The artifact looks however good too though, seems cheating a bit with pip in update_apidocs.sh worked 😛

Now the question is : do you agree with it ? Let me know once you have time to make a review (or if you want someone-else to do it ...)

[brownbaerchen]

Does this mean whatever can be displayed on GitHub can also be rendered on the website? Since GitHub is really picky, I dare not celebrate too early :D

[tlunet]

Does this mean whatever can be displayed on GitHub can also be rendered on the website? Since GitHub is really picky, I dare not celebrate too early :D

For now it works with basic Markdown synthax and emoji (need to wrap the m2r2 conversion from mardown to rst, see docs/convert_markdown.py script). Next stage would be to try including images, which should not be that complicated. We can start by adding the Time-X, EuroHPC, BMBF, etc ... logos on the README.md page.

Also, I still have to test whether the <details> html element can be translated to rst too ...

The thing is : with the m2r2 converting tool, you have a quick and safe way to translate from markdown to rst, and also take care about all the cross-files reference links. Then you just have add your own modifications to the rst files (in python string) before you write them down. In a way, you control the converting process to address your specific needs.

[pancetta]

This is really impressive and would ease quite a bit of documentation pain. I played with the doc artifact generated by this PR and things do look great, mostly!

The only thing that I found is that when clicking on the Contribution Guidelines, the TOC is missing on the right. Also, the Changelog seems to have the wrong level. Can you confirm and fix that?

[tlunet]

This is really impressive and would ease quite a bit of documentation pain. I played with the doc artifact generated by this PR and things do look great, mostly!

The only thing that I found is that when clicking on the Contribution Guidelines, the TOC is missing on the right. Also, the Changelog seems to have the wrong level. Can you confirm and fix that?

Yes, those are details to deal with directly in the rst generation, and since it was not too problematic for the website, I did not spend to much time on it. But I can try to solve it if you want => just have to fully understand how sphinx deals with levels and TOC ... 😅

[pancetta]

Be warned, though: the way I set up the website is really NOT how you should do it. It happens to work, but that's about it.

Anyway, I like your PR a lot! Want to merge now or later?

[tlunet]

Let me try to solve TOC and level first (there are also probably a few typo left). Also, looking again through it, I thought of some additional things, that should not be too long to implement :

• move the Changelog to a separate page, referenced from the Contribute section in the README (same level as CONTRIBUTING)
• try to add images in the README (project logos) and include them in the website
• add specific doku on how to build the documentation website and check if it renders correctly

Let me know if you don't want some of those points, or if you think about others

[pancetta]

Incredible work, thanks! Ready to merge?

[tlunet]

Yes, let's start with that !