jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
177 stars 28 forks source link

`repo_type` not used and `repo_name` can be intuitive #259

Closed 2bndy5 closed 1 year ago

2bndy5 commented 1 year ago

repo_type

I think this conf.py option repo_type was actually inherited from the sphinx-material theme. But it isn't used in any JS or HTML templates. Removing it could be considered a breaking change because removing the option from theme.conf would invalidate its usage. Unfortunately, the current docs state (as inherited from sphinx-material):

Must be one of github, gitlab or bitbucket.

which sounds misleadingly required.

repo_name

In accordance with upstream's behavior, the repo_name conf.py option can be automatically extracted from a given repo_url value. Currently, it is mandatory (as inherited from sphinx-material) without this added intuition, so this idea isn't a breaking change.

The URL structure for github, gitlab, and bitbucket all ends in user/repo_name. Sourceforge URLs or a URL starting with git:// do not use the same structure, but these aren't explicitly supported by upstream. In fact the JS really only expects github or gitlab URLs for fetching repo info (if consent permits). In conclusion, the repo_name should only be extracted if the domain is of github, gitlab, or bitbucket; any other git-hosting service (like svn) will require the repo_name set explicitly.