Restore rich Sphinx contributing doc, link from GitHub-Markdown doc#392
Conversation
|
|
|
Integration tests report: appsharing.space |
|
please update snapshots 🤷 |
| - This may be caused by having a `.gitignore` file in your home directory. | ||
| This is a [known issue with Nx](https://github.com/nrwl/nx/issues/27494). | ||
| The [only known workaround](https://github.com/nrwl/nx/issues/27494#issuecomment-2481207598) is to remove the `.gitignore` file from your home directory or to work in a location outside of the home directory tree. | ||
| Please check out [our documentation's contributing guide](https://jupytergis.readthedocs.io/en/latest/contributing.html). |
There was a problem hiding this comment.
Thanks @mfisher87, I'm happy with this, keeping in mind that we've #251 open which will allow both - rich Sphinx and contributing doc rendered on github too hopefully.
I'd be happy to know what @brichet thinks about the same before we go forward :)
There was a problem hiding this comment.
Even with MyST, I don't know that we can achieve rich online docs that are also available in rich format on GitHub either with includes or with symlinks just because of path issues 😭 For example:
.
├── CONTRIBUTING.md
└── docs
├── contributing.md
├── thing2.md
└── thing.md
CONTRIBUTING.md would need to link to thing2.md like [link](/docs/thing2.md), but docs/contributing.md would link to the same document with [link](/thing2.md). It's an implicit behavior we'd have to always keep in mind; in other repos where I saw this, contributors kept making mistakes with links because they weren't aware of these tradeoffs with the document was being included from outside the documentation dorectory.
Also, GitHub won't support any Sphinx plugins we use to add special directives like tabs that give the documentation a more logical flow!
There was a problem hiding this comment.
We should not keep this snapshot change; I see that the scale indicator at the bottom is incorrect.
There was a problem hiding this comment.
Posting a snapshot just in case, since it's not accessible anymore
mfisher87
force-pushed
the
restore-rich-contributing-doc
branch
from
51bc331 to
b2fbbff
Compare
|
Merging this PR since it definitely didn't cause the snapshot change. I'll open an issue! |
2 participants
Description
Keeps a CONTRIBUTING doc at the root of the repo, but it now links to our rich contributing documentation in ReadTheDocs!
Enables us to do important things like cross-link to the contributing documentation from other documentation.
Related discussions:
Checklist
Resolves #XXX.Failing lint checks can be resolved with:
pre-commit run --all-filesjlpm run lint📚 Documentation preview: https://jupytergis--392.org.readthedocs.build/en/392/
💡 JupyterLite preview: https://jupytergis--392.org.readthedocs.build/en/392/lite