-
Notifications
You must be signed in to change notification settings - Fork 1.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add sphinx
and sphinx_rtd_theme
as deps for a new docs
extra
#4643
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for looking into this!! Even though it's super simple, I have a couple of questions:
- Do we actually depend on
sphinx_rtd_theme
to 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
docs
extra 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
docs
extra that specifies what is required to build the documentation locally.To Do
docs/changelog.rst
near the top of the document.)