Add sphinx and sphinx_rtd_theme as deps for a new docs extra - #4643
Conversation
sampsyo
left a comment
There was a problem hiding this comment.
Thanks for looking into this!! Even though it's super simple, I have a couple of questions:
- Do we actually depend on
sphinx_rtd_themeto build the docs locally? At least here, I don't seem to use anything other than the default theme when building things… - Is the goal with the
docsextra just for manual installation, i.e., to let people manually type inpip install .[docs]or similar? Or is there some automated scenario I'm not yet thinking of that would use this extra?
Beets currently doesn't depend on it, but it has the theme applied by default when the documentation is compiled by readthedocs.io. I think it would be a good idea to use the same theme locally, so that whoever makes an edit to the docs can see immediately how it will be displayed in the "official" version.
Manual installation is the use case I had in mind, but, if the project ever wanted to move off readthedocs.io, the new Continuous Deployment infrastructure could use that extra to install the dependencies to build the docs. |
sampsyo
left a comment
There was a problem hiding this comment.
Cool; thanks for clarifying! Having this around as a manual option seems perfectly reasonable to me.
|
@JOJ0 Done! Please squash this to not pollute the master branch's history! :D |
|
I've seen worse commit hell. Merging ;-) (Also I'd like to leave changelog commit separately) |
Description
Currently, the dependencies to build the documentation are not specified anywhere.
This PR introduces a new
docsextra that specifies what is required to build the documentation locally.To Do
docs/changelog.rstnear the top of the document.)