Skip to content

Commit a09afb4

Browse files
pradyunsgpradyunsg
authored
Merge pull request #34 from pradyunsg/add-overrides-for-edit-and-view-links
Improve edit and view links, with overrides and `html_show_sourcelink` support
2 parents 9128bb0 + 7a441a9 commit a09afb4

File tree

4 files changed

+140
-111
lines changed

4 files changed

+140
-111
lines changed

‎docs/usage/components/edit-this-page.md

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This will add a single `a[href]` tag, with the text "Edit this page".
1616
You also need to declare the following in `theme.conf`'s `options` section:
1717

1818
```ini
19+
source_edit_link =
1920
source_repository =
2021
source_branch =
2122
source_directory =
@@ -34,8 +35,17 @@ html_theme_options = {
3435
}
3536
```
3637

37-
Those user-provided values are used to determine the link for editting the
38-
generated page on the hosting platform.
38+
```python
39+
html_theme_options = {
40+
"source_edit_link": "https://my.host/project/edit/docs/{filename}",
41+
"source_repository": "https://my.host/project",
42+
"source_branch": "main",
43+
"source_directory": "docs/",
44+
}
45+
```
46+
47+
Those user-provided values are used to determine the link for editing the
48+
generated page on their code hosting platform.
3949

4050
This component can be customised in a theme-specific manner in two ways, both of
4151
which require adding a new template file (typically,
@@ -58,26 +68,17 @@ which require adding a new template file (typically,
5868

5969
2. Overriding
6070

61-
This is done by depending on the `determine_page_edit_link` macro, to get the
62-
relevant URL and _not_ extending this file. This allows the theme to have
63-
complete control over the way the URL provided is used.
71+
This can be done by _not_ extending the base template. This allows the theme
72+
to have complete control over the way the URL provided is used. If a theme
73+
does this, it is also responsible for presenting warnings to the user when
74+
the user has not provided all the required configuration variables to the
75+
theme (see the sources of `edit-this-page.html`, after macros).
6476

65-
If a theme does this, it is also responsible for presenting warnings to the
66-
user when the user has not provided all the required configuration variables
67-
to the theme.
77+
It is possible to use the `determine_page_edit_link` macro, to get the
78+
relevant URL from the regular configuration (it assumes the user has it set).
6879

6980
```jinja
7081
{% from "basic-ng/components/edit-this-page.html" import determine_page_edit_link with context %}
7182
72-
{%- if page_source_suffix -%}
73-
{%- if READTHEDOCS and github_repo %}
74-
{% set url = "https://github.com/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" %}
75-
<a class="muted-link" href="{{ url }}">{{ _("Edit this page") }}</a>
76-
{%- elif theme_source_repository -%}
77-
{%- if not theme_source_branch -%}
78-
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
79-
{%- endif -%}
80-
<a class="muted-link" href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
81-
{%- endif -%}
82-
{%- endif -%}
83+
<a href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
8384
```

‎docs/usage/components/view-this-page.md

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,15 @@ to the source repository of the project.
1313

1414
This will add a single `a[href]` tag, with the text "View this page".
1515

16+
This uses the user-provided source repository links if provided. If they're not
17+
provided and the documentation is built with `html_copy_source = True` _and_
18+
`html_show_sourcelink = True` (which are the default), the link points to the
19+
Sphinx-copied sources.
20+
1621
You also need to declare the following in `theme.conf`'s `options` section:
1722

1823
```ini
24+
source_view_link =
1925
source_repository =
2026
source_branch =
2127
source_directory =
@@ -34,6 +40,15 @@ html_theme_options = {
3440
}
3541
```
3642

43+
```python
44+
html_theme_options = {
45+
"source_view_link": "https://my.host/project/view/docs/{filename}",
46+
"source_repository": "https://my.host/project",
47+
"source_branch": "main",
48+
"source_directory": "docs/",
49+
}
50+
```
51+
3752
Those user-provided values are used to determine the link for viewing the
3853
generated page on the hosting platform. Currently supported platforms are
3954
`https://github.com`, `https://bitbucket.org` and `https://gitlab.io/`.
@@ -59,26 +74,17 @@ which require adding a new template file (typically,
5974

6075
2. Overriding
6176

62-
This is done by depending on the `determine_page_view_link` macro, to get the
63-
relevant URL and _not_ extending this file. This allows the theme to have
64-
complete control over the way the URL provided is used.
77+
This can be done by _not_ extending the base template. This allows the theme
78+
to have complete control over the way the URL provided is used. If a theme
79+
does this, it is also responsible for presenting warnings to the user when
80+
the user has not provided all the required configuration variables to the
81+
theme (see the sources of `view-this-page.html`, after macros).
6582

66-
If a theme does this, it is also responsible for presenting warnings to the
67-
user when the user has not provided all the required configuration variables
68-
to the theme.
83+
It is possible to use the `determine_page_view_link` macro, to get the
84+
relevant URL from the regular configuration (it assumes the user has it set).
6985

7086
```jinja
7187
{% from "basic-ng/components/view-this-page.html" import determine_page_view_link with context %}
7288
73-
{%- if page_source_suffix -%}
74-
{%- if READTHEDOCS and github_repo %}
75-
{% set url = "https://github.com/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" %}
76-
<a class="muted-link" href="{{ url }}">{{ _("View this page") }}</a>
77-
{%- elif theme_source_repository -%}
78-
{%- if not theme_source_branch -%}
79-
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
80-
{%- endif -%}
81-
<a class="muted-link" href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
82-
{%- endif -%}
83-
{%- endif -%}
89+
<a href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
8490
```

‎src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html

Lines changed: 46 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,59 @@
11
{%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%}
22

33
{%- macro determine_page_edit_link() -%}
4-
{#- First, sanitise the trailing slashes. -#}
5-
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
6-
{%- set branch = theme_source_branch -%}
7-
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
8-
9-
{#- Figure out the document's source file path. -#}
10-
{%- set relative_path = pagename + page_source_suffix -%}
11-
{%- if not subdirectory -%}
12-
{%- set document_path = relative_path -%}
4+
{%- if theme_source_edit_link -%}
5+
{{ theme_source_edit_link.format(filename=pagename+page_source_suffix) }}
136
{%- else -%}
14-
{%- set document_path = subdirectory + "/" + relative_path -%}
15-
{%- endif -%}
7+
{#- First, sanitise the trailing slashes. -#}
8+
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
9+
{%- set branch = theme_source_branch -%}
10+
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
1611

17-
{#- Don't allow http:// URLs -#}
18-
{%- if repo.startswith(
19-
(
20-
"http://github.com/",
21-
"http://gitlab.com/",
22-
"http://bitbucket.org/",
23-
)
24-
) -%}
25-
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
26-
{#- Handle the relevant cases -#}
27-
{%- elif repo.startswith("https://github.com/") -%}
28-
{{ repo }}/edit/{{ branch }}/{{ document_path }}
29-
{%- elif repo.startswith("https://gitlab.com/") -%}
30-
{{ repo }}/-/edit/{{ branch }}/{{ document_path }}
31-
{%- elif repo.startswith("https://bitbucket.org/") -%}
32-
{{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }}
33-
{#- Fail with a warning -#}
34-
{%- else -%}
35-
{{ warning("Could not understand `source_repository` provided: " + repo) }}
12+
{#- Figure out the document's source file path. -#}
13+
{%- set relative_path = pagename + page_source_suffix -%}
14+
{%- if not subdirectory -%}
15+
{%- set document_path = relative_path -%}
16+
{%- else -%}
17+
{%- set document_path = subdirectory + "/" + relative_path -%}
18+
{%- endif -%}
19+
20+
{#- Don't allow http:// URLs -#}
21+
{%- if repo.startswith(
22+
(
23+
"http://github.com/",
24+
"http://gitlab.com/",
25+
"http://bitbucket.org/",
26+
)
27+
) -%}
28+
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
29+
{#- Handle the relevant cases -#}
30+
{%- elif repo.startswith("https://github.com/") -%}
31+
{{ repo }}/edit/{{ branch }}/{{ document_path }}
32+
{%- elif repo.startswith("https://gitlab.com/") -%}
33+
{{ repo }}/-/edit/{{ branch }}/{{ document_path }}
34+
{%- elif repo.startswith("https://bitbucket.org/") -%}
35+
{{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }}
36+
{#- Fail with a warning -#}
37+
{%- else -%}
38+
{{ warning(
39+
"Could not understand `source_repository` provided: " + repo + "\n" +
40+
"You should set `source_edit_link`, so that the edit link is presented."
41+
) }}
42+
{%- endif -%}
3643
{%- endif -%}
3744
{%- endmacro -%}
3845

46+
3947
{%- if page_source_suffix -%}
40-
{%- if theme_source_repository -%}
41-
{%- if not theme_source_branch -%}
42-
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
43-
{%- endif -%}
44-
{% block link_available %}
48+
{%- set can_find_edit_link = (
49+
(theme_source_edit_link and pagename)
50+
or (theme_source_repository and theme_source_branch)
51+
) -%}
52+
{%- if can_find_edit_link -%}
53+
{%- block link_available -%}
4554
<a href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
46-
{% endblock link_available %}
55+
{%- endblock link_available -%}
4756
{%- else -%}
48-
{% block link_not_available %}{% endblock %}
57+
{%- block link_not_available -%}{%- endblock -%}
4958
{%- endif -%}
5059
{%- endif -%}

‎src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html

Lines changed: 51 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,63 @@
11
{%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%}
22

33
{%- macro determine_page_view_link() -%}
4-
{#- First, sanitise the trailing slashes. -#}
5-
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
6-
{%- set branch = theme_source_branch -%}
7-
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
4+
{%- if theme_source_view_link -%}
5+
{{ theme_source_view_link.format(filename=pagename+page_source_suffix) }}
6+
{%- elif theme_source_repository -%}
7+
{#- First, sanitise the trailing slashes. -#}
8+
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
9+
{%- set branch = theme_source_branch -%}
10+
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
811

9-
{#- Figure out the document's source file path. -#}
10-
{%- set relative_path = pagename + page_source_suffix -%}
11-
{%- if not subdirectory -%}
12-
{%- set document_path = relative_path -%}
13-
{%- else -%}
14-
{%- set document_path = subdirectory + "/" + relative_path -%}
15-
{%- endif -%}
12+
{#- Figure out the document's source file path. -#}
13+
{%- set relative_path = pagename + page_source_suffix -%}
14+
{%- if not subdirectory -%}
15+
{%- set document_path = relative_path -%}
16+
{%- else -%}
17+
{%- set document_path = subdirectory + "/" + relative_path -%}
18+
{%- endif -%}
1619

17-
{#- Don't allow http:// URLs -#}
18-
{%- if repo.startswith(
19-
(
20-
"http://github.com/",
21-
"http://gitlab.com/",
22-
"http://bitbucket.org/",
23-
)
24-
) -%}
25-
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
26-
{#- Handle the relevant cases -#}
27-
{%- elif repo.startswith("https://github.com/") -%}
28-
{{ repo }}/blob/{{ branch }}/{{ document_path }}?plain=true
29-
{%- elif repo.startswith("https://gitlab.com/") -%}
30-
{{ repo }}/blob/{{ branch }}/{{ document_path }}
31-
{%- elif repo.startswith("https://bitbucket.org/") -%}
32-
{{ repo }}/src/{{ branch }}/{{ document_path }}
33-
{#- Fail with a warning -#}
34-
{%- else -%}
35-
{{ warning("Could not understand `source_repository` provided: " + repo) }}
20+
{#- Don't allow http:// URLs -#}
21+
{%- if repo.startswith(
22+
(
23+
"http://github.com/",
24+
"http://gitlab.com/",
25+
"http://bitbucket.org/",
26+
)
27+
) -%}
28+
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
29+
{#- Handle the relevant cases -#}
30+
{%- elif repo.startswith("https://github.com/") -%}
31+
{{ repo }}/blob/{{ branch }}/{{ document_path }}?plain=true
32+
{%- elif repo.startswith("https://gitlab.com/") -%}
33+
{{ repo }}/blob/{{ branch }}/{{ document_path }}
34+
{%- elif repo.startswith("https://bitbucket.org/") -%}
35+
{{ repo }}/src/{{ branch }}/{{ document_path }}
36+
{#- Fail with a warning -#}
37+
{%- else -%}
38+
{{ warning(
39+
"Could not understand `source_repository` provided: " + repo + "\n" +
40+
"You should set `source_view_link`, so that the view link is presented."
41+
) }}
42+
{%- endif -%}
43+
{%- elif show_source and has_source -%}
44+
{{ pathto('_sources/' + sourcename, true) }}
45+
{%- endif -%}
3646
{%- endif -%}
3747
{%- endmacro -%}
3848

49+
3950
{%- if page_source_suffix -%}
40-
{%- if theme_source_repository -%}
41-
{%- if not theme_source_branch -%}
42-
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
43-
{%- endif -%}
44-
{% block link_available %}
45-
<a href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
46-
{% endblock link_available %}
51+
{%- set can_find_view_link = (
52+
(theme_source_view_link and pagename)
53+
or (show_source and has_source and sourcename)
54+
or (theme_source_repository and theme_source_branch)
55+
) -%}
56+
{%- if can_find_view_link -%}
57+
{%- block link_available -%}
58+
<a href="{{ determine_page_view_link() }}">{{ _("View sources") }}</a>
59+
{%- endblock link_available -%}
4760
{%- else -%}
48-
{% block link_not_available %}{% endblock %}
61+
{%- block link_not_available -%}{%- endblock -%}
4962
{%- endif -%}
5063
{%- endif -%}

0 commit comments

Comments
 (0)