helmholtz-analytics / heat

Distributed tensors and Machine Learning framework with GPU and MPI acceleration in Python

https://heat.readthedocs.io/

MIT License

212 stars 53 forks source link

Unify documentation GitHub/ReadTheDocs #1242

Open ClaudiaComito opened 1 year ago

ClaudiaComito commented 1 year ago

Related

1186

Feature functionality At this time our infos on the GitHub repo, esp. onboarding and contributing instructions, have diverged from the ReadTheDocs docs

We need to unify docs location and cross-references so the info is consistent and updates unambiguous.

Existing markdown instructions on this repo should be ported to .rst and moved to doc/. Updates to our README.md should be automatically picked up in docs/introduction.rst. And so on.

This is a mid-term goal. I think it's OK if it doesn't get solved immediately, as long as the solution no longer involves manual porting from GitHub to ReadTheDocs and viceversa.

github-actions[bot] commented 11 months ago

This issue is stale because it has been open for 60 days with no activity.

ClaudiaComito commented 8 months ago

This issue is still open.

We now have new jupiter notebooks #1406 in the tutorials directory. What still needs to be done here:

[ ] implement sphinx tutorials as jupyter notebooks (all done but dpnn)
[ ] have sphinx source files point to notebooks https://docs.readthedocs.io/en/stable/guides/jupyter.html (thanks @JuanPedroGHM )
[ ] README, getting started, contributing etc: there should be one source file for all of these (unclear what's the best way to do it)
[ ] update sphinx theme so that it's compatibe with compatible with sphinx >= 8, see #1616 (added Aug 19)

mtar commented 8 months ago

MyST looks quite interesting https://myst-parser.readthedocs.io/en/latest/index.html#

ClaudiaComito commented 3 months ago

Adding to the checklist:

[ ] update sphinx theme so that it's compatibe with compatible with sphinx >= 8, see #1616