Improve and restructure README, plus other minor docs fixes #1245
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1245 +/- ##
=======================================
Coverage 74.84% 74.84%
=======================================
Files 67 67
Lines 4631 4631
=======================================
Hits 3466 3466
Misses 1165 1165 🚀 New features to boost your workflow:
|
datalab
|
||||||||||||||||||||||||||||
| Project |
datalab
|
| Branch Review |
update-readme
|
| Run status |
|
| Run duration | 07m 03s |
| Commit |
|
| Committer | Yue Wu |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
Failures
|
0
|
Flaky
|
0
|
Pending
|
0
|
Skipped
|
0
|
Passing
|
336
|
| View all changes introduced in this branch ↗︎ | |
There was a problem hiding this comment.
Conscious of bikeshedding this too much, but could you, if you agree:
- refactor the second para into bulletpoints of "features" and add extra points describing the Python API and the federation?
- move the arch diagram a bit lower to the design philosophy section? it's a bit in your face if it can't be made any smaller
|
Made changes. TIL "bikeshedding" |
|
Thanks @yue-here! Only thing I want to check is how this looks when rendered at docs.datalab-org.io (the readthedocs status check will give us a preview once its finished), we may need to do a bit of extra work to get the nice mermaid diagram there too (the base page of the docs is just a symlink to this README). |
It looks really good already in light mode for me, but not dark mode: https://the-datalab--1245.org.readthedocs.build/en/1245/ @yue-here can you try to figure out the right styling? Might need some kind of @prefers-colour-scheme CSS, or just avoiding hardcoding colours and letting the theming sort itself out |
|
Based on my limited styling knowledge it seems that the hardcoded colors in the original mermaid are changed by the RTD theming, and the diagram is in a shadow DOM which needs additional frontend wizardy beyond my ken to mess with. I've hacked it using transparency so that the diagram is legible in both themes. Will make one more commit to make it look slightly better. |
Co-authored-by: Josh Bocarsly <32345545+jdbocarsly@users.noreply.github.com>
deployment.md no longer exists, this removes the broken link in the first instance and changes the link to https://docs.datalab-org.io/en/stable/deployment/ in the second
There was a problem hiding this comment.
I've just shifted and added a few bits to this PR, but I think its now in a good state. I've reintroduced the old video for further discussion #1258, as well as introducing fixes from @yue-here's other PRs, including:
- linking to the CHANGELOG everywhere
- expanding contributions and funding section (@jdbocarsly feel free to add your own acknowledgements here)
- move the install docs to be purely read online with proper formatting, rather than the hacky GH markdown version
- spell-checked entire documentation
- tweaked some mkdocs options to make the TOC nicer
Any further changes I think we can defer until a future PR after the next release.
Update readme.md to higher level description, added mermaid diagram to replace video.