Skip to content
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

Merged
merged 4 commits into from
Mar 8, 2023
Merged

Add sphinx and sphinx_rtd_theme as deps for a new docs extra #4643

merged 4 commits into from
Mar 8, 2023

Conversation

Steffo99
Copy link
Contributor

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

  • Changelog. (Add an entry to docs/changelog.rst near the top of the document.)

Copy link
Member

@sampsyo sampsyo left a 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 in pip install .[docs] or similar? Or is there some automated scenario I'm not yet thinking of that would use this extra?

docs/changelog.rst Outdated Show resolved Hide resolved
@Steffo99
Copy link
Contributor Author

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…
@sampsyo

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.

Is the goal with the docs extra just for manual installation, i.e., to let people manually type in pip install .[docs] or similar? Or is there some automated scenario I'm not yet thinking of that would use this extra?
@sampsyo

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.

@Steffo99 Steffo99 requested a review from sampsyo January 23, 2023 00:28
Copy link
Member

@sampsyo sampsyo left a 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
Copy link
Member

JOJ0 commented Mar 8, 2023

Hi @Steffo99, I would like to take over this PR. If you could fix conflicts in changelog.rst I think we are ready to merge since @sampsyo had approved it already :-)

@Steffo99
Copy link
Contributor Author

Steffo99 commented Mar 8, 2023

@JOJ0 Done!

Please squash this to not pollute the master branch's history! :D

@JOJ0
Copy link
Member

JOJ0 commented Mar 8, 2023

I've seen worse commit hell. Merging ;-)

(Also I'd like to leave changelog commit separately)

@JOJ0 JOJ0 merged commit 8bbaefb into beetbox:master Mar 8, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants