From 71ebf353e6fe8827d8fb2d6c74a077f336782eca Mon Sep 17 00:00:00 2001 From: Felix Eckhofer Date: Thu, 15 Mar 2018 14:31:51 +0100 Subject: [PATCH] Add support for GitLab repositories (#1435) Note that the icons in the themes will not show up until FontAwesome is updated to at least version 4.6 and/or an up-to-date version of the upstream readthedocs css is imported. This commit also fixes a slight documentation error regarding the default value of `repo_name` and removes some tautological tests. --- docs/user-guide/configuration.md | 36 +++++++++++---------- mkdocs/config/config_options.py | 4 ++- mkdocs/config/defaults.py | 3 +- mkdocs/tests/config/config_options_tests.py | 17 ++++++++-- mkdocs/themes/mkdocs/nav.html | 4 +++ mkdocs/themes/readthedocs/breadcrumbs.html | 2 ++ mkdocs/themes/readthedocs/versions.html | 2 ++ 7 files changed, 46 insertions(+), 22 deletions(-) diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 7ed48b26..333b7e67 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -35,7 +35,8 @@ URL to the generated HTML header. ### repo_url -When set, provides a link to your GitHub or Bitbucket repository on each page. +When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) +on each page. ```yaml repo_url: https://github.com/example/repository/ @@ -45,10 +46,10 @@ repo_url: https://github.com/example/repository/ ### repo_name -When set, provides a link to your GitHub or Bitbucket repository on each page. +When set, provides the name for the link to your repository on each page. -**default**: `'GitHub'` or `'Bitbucket'` if the `repo_url` matches those -domains, otherwise `null` +**default**: `'GitHub'`, `'Bitbucket'` or `'GitLab'` if the `repo_url` matches +those domains, otherwise the hostname from the `repo_url`. ### edit_uri @@ -86,14 +87,14 @@ edit_uri: root/path/docs/ ``` !!! note - On a few known hosts (specifically GitHub and Bitbucket), the `edit_uri` is - derived from the 'repo_url' and does not need to be set manually. Simply - defining a `repo_url` will automatically populate the `edit_uri` config - setting. + On a few known hosts (specifically GitHub, Bitbucket and GitLab), the + `edit_uri` is derived from the 'repo_url' and does not need to be set + manually. Simply defining a `repo_url` will automatically populate the + `edit_uri` configs setting. - For example, for a GitHub-hosted repository, the `edit_uri` would be - automatically set as `edit/master/docs/` (Note the `edit` path and `master` - branch). + For example, for a GitHub- or GitLab-hosted repository, the `edit_uri` + would be automatically set as `edit/master/docs/` (Note the `edit` path + and `master` branch). For a Bitbucket-hosted repository, the equivalent `edit_uri` would be automatically set as `src/default/docs/` (note the `src` path and `default` @@ -105,15 +106,16 @@ edit_uri: root/path/docs/ string to disable the automatic setting. !!! warning - On GitHub, the default "edit" path (`edit/master/docs/`) opens the page in - the online GitHub editor. This functionality requires that the user have and - be logged in to a GitHub account. Otherwise, the user will be redirected to - a login/signup page. Alternatively, use the "blob" path + On GitHub and GitLab, the default "edit" path (`edit/master/docs/`) opens + the page in the online editor. This functionality requires that the user + have and be logged in to a GitHub/GitLab account. Otherwise, the user will + be redirected to a login/signup page. Alternatively, use the "blob" path (`blob/master/docs/`) to open a read-only view, which supports anonymous access. -**default**: `edit/master/docs/` or `src/default/docs/` for GitHub or Bitbucket -repos, respectively, if `repo_url` matches those domains, otherwise `null` +**default**: `edit/master/docs/` for GitHub and GitLab repos or +`src/default/docs/` for a Bitbucket repo, if `repo_url` matches those domains, +otherwise `null` ### site_description diff --git a/mkdocs/config/config_options.py b/mkdocs/config/config_options.py index 87c09a82..9a7eb0b6 100644 --- a/mkdocs/config/config_options.py +++ b/mkdocs/config/config_options.py @@ -260,12 +260,14 @@ class RepoURL(URL): config['repo_name'] = 'GitHub' elif repo_host == 'bitbucket.org': config['repo_name'] = 'Bitbucket' + elif repo_host == 'gitlab.com': + config['repo_name'] = 'GitLab' else: config['repo_name'] = repo_host.split('.')[0].title() # derive edit_uri from repo_name if unset if config['repo_url'] is not None and edit_uri is None: - if repo_host == 'github.com': + if repo_host == 'github.com' or repo_host == 'gitlab.com': edit_uri = 'edit/master/docs/' elif repo_host == 'bitbucket.org': edit_uri = 'src/default/docs/' diff --git a/mkdocs/config/defaults.py b/mkdocs/config/defaults.py index 7a82a5b7..2e936958 100644 --- a/mkdocs/config/defaults.py +++ b/mkdocs/config/defaults.py @@ -68,7 +68,8 @@ DEFAULT_SCHEMA = ( # A name to use for the link to the project source repo. # Default, If repo_url is unset then None, otherwise - # "GitHub" or "Bitbucket" for known url or Hostname for unknown urls. + # "GitHub", "Bitbucket" or "GitLab" for known url or Hostname + # for unknown urls. ('repo_name', config_options.Type(utils.string_types)), # Specify a URI to the docs dir in the project source repo, relative to the diff --git a/mkdocs/tests/config/config_options_tests.py b/mkdocs/tests/config/config_options_tests.py index 87394fe5..17c4141b 100644 --- a/mkdocs/tests/config/config_options_tests.py +++ b/mkdocs/tests/config/config_options_tests.py @@ -172,7 +172,6 @@ class RepoURLTest(unittest.TestCase): option = config_options.RepoURL() config = {'repo_url': "https://github.com/mkdocs/mkdocs"} option.post_validation(config, 'repo_url') - self.assertEqual(config['repo_url'], config['repo_url']) self.assertEqual(config['repo_name'], "GitHub") def test_repo_name_bitbucket(self): @@ -180,15 +179,20 @@ class RepoURLTest(unittest.TestCase): option = config_options.RepoURL() config = {'repo_url': "https://bitbucket.org/gutworth/six/"} option.post_validation(config, 'repo_url') - self.assertEqual(config['repo_url'], config['repo_url']) self.assertEqual(config['repo_name'], "Bitbucket") + def test_repo_name_gitlab(self): + + option = config_options.RepoURL() + config = {'repo_url': "https://gitlab.com/gitlab-org/gitlab-ce/"} + option.post_validation(config, 'repo_url') + self.assertEqual(config['repo_name'], "GitLab") + def test_repo_name_custom(self): option = config_options.RepoURL() config = {'repo_url': "https://launchpad.net/python-tuskarclient"} option.post_validation(config, 'repo_url') - self.assertEqual(config['repo_url'], config['repo_url']) self.assertEqual(config['repo_name'], "Launchpad") def test_edit_uri_github(self): @@ -205,6 +209,13 @@ class RepoURLTest(unittest.TestCase): option.post_validation(config, 'repo_url') self.assertEqual(config['edit_uri'], 'src/default/docs/') + def test_edit_uri_gitlab(self): + + option = config_options.RepoURL() + config = {'repo_url': "https://gitlab.com/gitlab-org/gitlab-ce/"} + option.post_validation(config, 'repo_url') + self.assertEqual(config['edit_uri'], 'edit/master/docs/') + def test_edit_uri_custom(self): option = config_options.RepoURL() diff --git a/mkdocs/themes/mkdocs/nav.html b/mkdocs/themes/mkdocs/nav.html index 686cf00f..a2cbef28 100644 --- a/mkdocs/themes/mkdocs/nav.html +++ b/mkdocs/themes/mkdocs/nav.html @@ -78,6 +78,8 @@ Edit on {{ config.repo_name }} {%- elif config.repo_name == 'Bitbucket' -%} Edit on {{ config.repo_name }} + {%- elif config.repo_name == 'GitLab' -%} + Edit on {{ config.repo_name }} {%- else -%} Edit on {{ config.repo_name }} {%- endif -%} @@ -90,6 +92,8 @@ {{ config.repo_name }} {%- elif config.repo_name == 'Bitbucket' -%} {{ config.repo_name }} + {%- elif config.repo_name == 'GitLab' -%} + {{ config.repo_name }} {%- else -%} {{ config.repo_name }} {%- endif -%} diff --git a/mkdocs/themes/readthedocs/breadcrumbs.html b/mkdocs/themes/readthedocs/breadcrumbs.html index b7311ff1..efc2ab95 100644 --- a/mkdocs/themes/readthedocs/breadcrumbs.html +++ b/mkdocs/themes/readthedocs/breadcrumbs.html @@ -19,6 +19,8 @@ class="icon icon-github" {%- elif config.repo_name|lower == 'bitbucket' %} class="icon icon-bitbucket" + {%- elif config.repo_name|lower == 'gitlab' %} + class="icon icon-gitlab" {% endif %}> Edit on {{ config.repo_name }} {% endif %} {%- endblock %} diff --git a/mkdocs/themes/readthedocs/versions.html b/mkdocs/themes/readthedocs/versions.html index 8a0ecef7..cbf23215 100644 --- a/mkdocs/themes/readthedocs/versions.html +++ b/mkdocs/themes/readthedocs/versions.html @@ -4,6 +4,8 @@ GitHub {% elif config.repo_name == 'Bitbucket' %} BitBucket + {% elif config.repo_name == 'GitLab' %} + GitLab {% endif %} {% if page.previous_page %} « Previous