Skip to content

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

Merged
JOJ0 merged 4 commits into
beetbox:masterfrom
Steffo99:sphinx-deps
Mar 8, 2023
Merged

Add sphinx and sphinx_rtd_theme as deps for a new docs extra#4643
JOJ0 merged 4 commits into
beetbox:masterfrom
Steffo99:sphinx-deps

Conversation

@Steffo99

Copy link
Copy Markdown
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.)

@sampsyo sampsyo left a comment

Copy link
Copy Markdown
Member

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?

Comment thread docs/changelog.rst Outdated
@Steffo99

Copy link
Copy Markdown
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

@sampsyo sampsyo left a comment

Copy link
Copy Markdown
Member

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

JOJ0 commented Mar 8, 2023

Copy link
Copy Markdown
Member

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

Steffo99 commented Mar 8, 2023

Copy link
Copy Markdown
Contributor Author

@JOJ0 Done!

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

@JOJ0

JOJ0 commented Mar 8, 2023

Copy link
Copy Markdown
Member

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