using sphinx-book-theme-1.0.0 requires repository_provider

[kbucheli]

Building the Jupyter Book as HTML newly requires a repository_provider to add GitLab-Buttons. How to add that? The documentation misses such a setting.

Our configuration is

...
repository:
  url: https://git.psi.ch/linux-infra/documentation
  branch: master

# Add GitLab buttons
html:
  use_issues_button: true
  use_repository_button: true

which then causes

Sphinx error:
Provider not recognized in repository url https://git.psi.ch/linux-infra/documentation. If you're using a custom provider URL, specify `repository_provider`
Traceback (most recent call last):
  File "/usr/local/lib/python3.9/dist-packages/jupyter_book/sphinx.py", line 114, in build_sphinx
    app = Sphinx(
  File "/usr/local/lib/python3.9/dist-packages/sphinx/application.py", line 256, in __init__
    self._init_builder()
  File "/usr/local/lib/python3.9/dist-packages/sphinx/application.py", line 314, in _init_builder
    self.events.emit('builder-inited')
  File "/usr/local/lib/python3.9/dist-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/usr/local/lib/python3.9/dist-packages/sphinx_book_theme/header_buttons/__init__.py", line 175, in update_context_with_repository_info
    raise SphinxError(
sphinx.errors.SphinxError: Provider not recognized in repository url https://git.psi.ch/linux-infra/documentation. If you're using a custom provider URL, specify `repository_provider`

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/bin/jupyter-book", line 8, in <module>
    sys.exit(main())
  File "/usr/lib/python3/dist-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/jupyter_book/cli/main.py", line 317, in build
    builder_specific_actions(
  File "/usr/local/lib/python3.9/dist-packages/jupyter_book/cli/main.py", line 525, in builder_specific_actions
    raise RuntimeError(_message_box(msg, color="red", doprint=False)) from result

This worked before the release v0.15.0.

Versions:

• jupyter-book-0.15.0
• sphinx-5.0.2
• sphinx-book-theme-1.0.0

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[oscarbranson]

This is also an issue when using a URL for a GitHub organisation (e.g. see the build error here).

This arises from this line in header_buttons/_init_.py.

For example, for my repo:

repo_url = "https://quantitative-environmental-science.github.io/Notes/"

provider_url, org, repo = repo_url.strip("/").rsplit("/", 2)

provider_url

> 'https:/'

Which is invalid.

Happy to specify repository_provider, as noted in the error message, but it's not clear where this goes in _config.yml. Have tried all combinations of:

repository:
  repository_provider: github
  provider: github

html:
  repository_provider: github
  provider: github

None worked...

[lukasbindreiter]

Just did some more digging into the issue, since we encountered it as well.

I took a look at the opts we receive here: https://github.com/executablebooks/sphinx-book-theme/blob/6601a2ff1e5a5d51d784f1e6cafd4ed11cb38c4f/src/sphinx_book_theme/header_buttons/init.py#L141

when trying out all of the following:

repository:
  repository_provider: github
  provider: github

html:
  repository_provider: github
  provider: github

No matter what I try, provider never ends up as a key in there. Instead, these are the available keys in opts: ['search_bar_text', 'launch_buttons', 'path_to_docs', 'repository_url', 'repository_branch', 'extra_footer', 'home_page_in_toc', 'announcement', 'analytics', 'use_repository_button', 'use_edit_page_button', 'use_issues_button']

The underlying _get_theme_options seems to be this: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/init.py#L35 And both possible return values app.builder.theme_options and app.config.html_theme_options lack any trace of a provider.

Note however, the repository_url is correctly set to the url specified in the config.

[agoose77]

To explain what's going on here, Jupyter Book's repository section is manually mapped onto the Sphinx configuration html_theme_options. As we don't currently handle the provider options, you'd need to set them using the Sphinx escape hatch (which I've not tested):

sphinx:
  recursive_update: true
  config:
    html_theme_options:
      repository_provider: custom      

The recursive update just means that we don't clobber the existing settings. This maps onto the settings in this section: https://sphinx-book-theme.readthedocs.io/en/stable/components/source-files.html#manually-specify-the-provider

[vincentxavier]

As we don't currently handle the provider options, you'd need to set them using the Sphinx escape hatch (which I've not tested):

Seems to work. Is there any chance this will be integrated in the yaml_to_sphinx function and therefore in the _config.yml. ? At least, it should be added in the documentation.

[xesf]

sphinx:
  recursive_update: true
  config:
    html_theme_options:
      repository_provider: custom

I got it working by specifying repository_url as well. Since we have a github enterprise, I have changed repository_provider to github

[Australopiticus]

the following worked for me (using a custom gitlab repository)

in the config.yml file:

sphinx:
  recursive_update: true
    config:
      html_theme_options:
        repository_provider: https://my.provider.com
      html_context:
        gitlab_url: https://my.provider.com/my
        gitlab_repo: repository
        gitlab_user: ""
        gitlab_version: main
        doc_path: source

repository:
  url: https://my.provider.com/my/repository

It' basically the same as agoose77 proposed, but I also had to set the html_context otherwise I would get

Missing required value for `use_edit_page_button`. Ensure one set of the following in your `html_context` configuration: [('bitbucket_user', 'bitbucket_repo', 'bitbucket_version'), ('github_user', 'github_repo', 'github_version'), ('gitlab_user', 'gitlab_repo', 'gitlab_version')]

[buti1021]

the following worked for me (using a custom gitlab repository)

in the config.yml file:

sphinx:
  recursive_update: true
    config:
      html_theme_options:
        repository_provider: https://my.provider.com
      html_context:
        gitlab_url: https://my.provider.com/my
        gitlab_repo: repository
        gitlab_user: ""
        gitlab_version: main
        doc_path: source

repository:
  url: https://my.provider.com/my/repository

It' basically the same as agoose77 proposed, but I also had to set the html_context otherwise I would get

Missing required value for `use_edit_page_button`. Ensure one set of the following in your `html_context` configuration: [('bitbucket_user', 'bitbucket_repo', 'bitbucket_version'), ('github_user', 'github_repo', 'github_version'), ('gitlab_user', 'gitlab_repo', 'gitlab_version')]

Worked for me however the indentation seems to be slighty wrong:

sphinx:
  recursive_update: true
  config:
    html_theme_options:
      repository_provider: https://my.provider.com
    html_context:
      gitlab_url: https://my.provider.com/my
      gitlab_repo: repository
      gitlab_user: ""
      gitlab_version: main
      doc_path: source

repository:
  url: https://my.provider.com/my/repository```