📚 Add RTD documentation #23
Conversation
The simplest implementation of RTD documentation!
|
I'd like the rebuild fix in a separate PR, as it's an organization policy for all merges to be squashed. |
|
strange policy, fair enough |
|
It's to enforce separation of concerns, as the primary contributors to the projects are usually external. Plus merge commits can get messy if the contributor isn't all that familiar with git, which is common in our case. |
|
done 👍 |
chrisjsewell
changed the title
There was a problem hiding this comment.
I think it would be better to keep the documentation in rST format, as our main project https://github.com/wpilibsuite/frc-docs uses it extensively (the reason we wrote all these extensions :) and possibly more). However, I don't feel like we should rewrite the README especially with how simple it is. I'll okay using myst.
However, I'd like to keep things consistent with our other repositories and using sphinx_rtd_theme with the logo using the rediraffe logo. Additionally, using sphinx-build has had an iffy chance working on windows (due to scripts sometimes not being executable), so could you add in the make.bat and make files that are generated when you run the sphinx-quickstart command.
I'd like to adopt our documentation style guide into this repository and eventually add our other CI checks for the documentation. See here for our style guide.
docs/conf.py
Outdated
| master_doc = "index" | ||
| project = "sphinxext-rediraffe" | ||
|
|
||
| exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] |
There was a problem hiding this comment.
I don't think excluding anything but _build is necessary, right?
There was a problem hiding this comment.
yeh this is what we use in our excutablebooks packages, but just _build should generally be fine.
You know that myst supports all these extensions (it supports "every" sphinx extension)? I will be adding myst to the sphinx-tabs documentation at some point. But enough of the sales pitch lol, I implemented your review changes
Out of interest, you've had this issue recently? I don't use Windows (because its rubbish 😛) so I don't know personally, but I haven't heard of anyone having an issue with python console_script entry points.
I would suggest creating a FYI you can now have readthedocs directly run CI: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html Also, fancy releasing a v0.2.2 soon. I've already had people complaining about rebuilds failing for jupyter-book docs 😬 |
|
It's been pushed. And I'm aware of RTD CI, as we do use it. However, it's very difficult to replicate the RTD build environment exactly, so our CI exists to replicate a "normal" build. Additionally it tests other things such as spelling, image size, verifying all links are valid, valid redirects (this extension). |
Fair, I'll have to check it out some time 👍 |
thanks 😄 |
|
@Daltz333 status update on this? |
|
The theme should be switched to furo to match sphinxext-opengraph. |
The simplest implementation of RTD documentation!
Simply run
tox -e docs-cleanto test, andtox -e docs-updateto try rebuilding(obviously a maintainer will need to add it on RTD)
In doing this, I realised that the rebuild fix (#19) wasn't actually working properly.
This is because the sphinx
envdoes not get re-saved afterbuild-finishedevents.So instead you'll see that I now read/write a JSON file in the build folder. This is also easier to inspect manually 😄