Readthedocs and documentation updates #1153
Conversation
|
alrighty, the build is green (https://readthedocs.org/projects/qhub-cloud/builds/16306372/) and can deploy (https://docs.qhub.dev/en/dox-fixes/). |
|
Awesome!! Thanks so much @tonyfast 💪 |
| sphinx-material | ||
| sphinxcontrib-bibtex | ||
| stringcase | ||
| jupyter-book |
There was a problem hiding this comment.
Hi @tonyfast, is this enough for building the docs (I know that it worked based on the succeeded build you provided)? I noticed that it has all the sphinx-related dependencies that we might need, but is there anything else we need to add as well?
There was a problem hiding this comment.
jupyter-book has a ton of dependencies. most of them are to incorporate markdown/notebooks as sphinx documentation source. all those prior deps are taken care of by jupyter-book.
| from nox import session | ||
|
|
||
|
|
||
| @session(reuse_venv=True) | ||
| def docs(session): | ||
| session.install("-e.") | ||
| session.install("-rdocs/requirements.txt") | ||
| session.run("sphinx-build", "docs", "_build/html") |
There was a problem hiding this comment.
I was reading the nox description and it seems very interesting, but I didn't quite understand how it is been used here exactly...
There was a problem hiding this comment.
sorry i missed that description. i added instructions to docs/README.md for building the docs. you'll need nox, pip install nox. run the nox docs session as:
nox -s docs
nox is a tool to ensure that sphinx builds in its own virtual environment, and doesn't effect the developer's primary environments. its specifically good for something like jupyter-book that has a lot of dependencies that are better isolated from other environments. also, it provides a convenient cli that can work locally/ci.
|
we could add it as a dev dependency, but that might make the most sense if we can get linting and testing to use |
currently readthedocs is failing on builds because qhub isn't installed. this pull request fixes that issue and introduces local documentation build support with nox.
when i make this pull requests, readthedocs should build us some docs or give us errors that hint at fixes.