Customization options for bitbucket, gitlab, and github are undocumented

[jpsenior]

I had to search the source-code to learn of the existence of these options for 'edit page' links. These should be documented properly with descriptions of their usages.

[Blendify]

Yeah I need to write some documentation.

[peterjc]

Based on #231 (comment) from @IKavanagh (thank you!), you can do the following in your conf.py file:

html_context = {
  "display_github": True, # Add 'Edit on Github' link instead of 'View page source'
  "github_user": "peterjc",
  "github_repo": project,  # assuming an exact match
  "github_version": "master",
  "conf_py_path": "/doc/", # needs leading and trailing slashes!
  # "source_suffix": source_suffix,
}

I've not explored why conf_py_path is called that, but it seems to be the relative path from the GitHub repository root to your documentation folder (where conf.py lives etc), and it needs leading and trailing slashes.

I have not needed to set source_suffix myself yet.

e.g. peterjc/thapbi-pict@9ec5300

If you need to over-ride this in any particular *.rst files, for example automatically generated ones which are not in GitHub, they need a line like the following added at the start:

:github_url: https://github.com/peterjc/...

e.g. peterjc/thapbi-pict@f14b1df does this via a function in conf.py

[cglacet]

The example show here does seem to work fine for gitlab, on the other hand it doesn't open the edit view but rather the main view, is that normal?

[stsewd]

@cglacet you can customize that with the vcs_pageview_mode option (defaults to blob for gitlab, but currently is broken #1010

[thompol]

What would be the config for GitLab users?

EDIT: I figured it out by looking at the source code. This is it:

html_context = {
  'display_gitlab': True,
  'gitlab_host': 'git.example.com',
  'gitlab_user': 'example',
  'gitlab_repo': 'example,
  'gitlab_version': 'master/',
}

[jreed1701]

While on the subject, the URL for bitbucket is hardcoded to be "bitbucket.org"

sphinx_rtd_theme/sphinx_rtd_theme/breadcrumbs.html

Lines 41 to 47 in 0da22b8

	{%- elif display_bitbucket %}
	{%- if check_meta and 'bitbucket_url' in meta %}
	<!-- User defined Bitbucket URL -->
	<a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
	{%- else %}
	<a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}?mode={{ theme_vcs_pageview_mode or "view" }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
	{%- endif %}