Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve edit and view links, with overrides and html_show_sourcelink support #34

Merged
merged 3 commits into from
Jul 18, 2022
Merged

Improve edit and view links, with overrides and html_show_sourcelink support #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f95ea65
Add user-provided overrides for edit and view links
pradyunsg Jul 10, 2022
9437587
Make `view-this-page` fall-back to Sphinx's copied sources
pradyunsg Jul 10, 2022
7a441a9
Only use `source_{view,edit}_link` on pages with `pagename`
pradyunsg Jul 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions docs/usage/components/edit-this-page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ This will add a single `a[href]` tag, with the text "Edit this page".
You also need to declare the following in `theme.conf`'s `options` section:

```ini
source_edit_link =
source_repository =
source_branch =
source_directory =
Expand All @@ -34,8 +35,17 @@ html_theme_options = {
}
```

Those user-provided values are used to determine the link for editting the
generated page on the hosting platform.
```python
html_theme_options = {
"source_edit_link": "https://my.host/project/edit/docs/{filename}",
"source_repository": "https://my.host/project",
"source_branch": "main",
"source_directory": "docs/",
}
```

Those user-provided values are used to determine the link for editing the
generated page on their code hosting platform.

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

2. Overriding

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

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

```jinja
{% from "basic-ng/components/edit-this-page.html" import determine_page_edit_link with context %}

{%- if page_source_suffix -%}
{%- if READTHEDOCS and github_repo %}
{% set url = "https://github.com/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" %}
<a class="muted-link" href="{{ url }}">{{ _("Edit this page") }}</a>
{%- elif theme_source_repository -%}
{%- if not theme_source_branch -%}
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
{%- endif -%}
<a class="muted-link" href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
{%- endif -%}
{%- endif -%}
<a href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
```
40 changes: 23 additions & 17 deletions docs/usage/components/view-this-page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,15 @@ to the source repository of the project.

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

This uses the user-provided source repository links if provided. If they're not
provided and the documentation is built with `html_copy_source = True` _and_
`html_show_sourcelink = True` (which are the default), the link points to the
Sphinx-copied sources.

You also need to declare the following in `theme.conf`'s `options` section:

```ini
source_view_link =
source_repository =
source_branch =
source_directory =
Expand All @@ -34,6 +40,15 @@ html_theme_options = {
}
```

```python
html_theme_options = {
"source_view_link": "https://my.host/project/view/docs/{filename}",
"source_repository": "https://my.host/project",
"source_branch": "main",
"source_directory": "docs/",
}
```

Those user-provided values are used to determine the link for viewing the
generated page on the hosting platform. Currently supported platforms are
`https://github.com`, `https://bitbucket.org` and `https://gitlab.io/`.
Expand All @@ -59,26 +74,17 @@ which require adding a new template file (typically,

2. Overriding

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

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

```jinja
{% from "basic-ng/components/view-this-page.html" import determine_page_view_link with context %}

{%- if page_source_suffix -%}
{%- if READTHEDOCS and github_repo %}
{% set url = "https://github.com/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" %}
<a class="muted-link" href="{{ url }}">{{ _("View this page") }}</a>
{%- elif theme_source_repository -%}
{%- if not theme_source_branch -%}
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
{%- endif -%}
<a class="muted-link" href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
{%- endif -%}
{%- endif -%}
<a href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
```
83 changes: 46 additions & 37 deletions src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,59 @@
{%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%}

{%- macro determine_page_edit_link() -%}
{#- First, sanitise the trailing slashes. -#}
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
{%- set branch = theme_source_branch -%}
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}

{#- Figure out the document's source file path. -#}
{%- set relative_path = pagename + page_source_suffix -%}
{%- if not subdirectory -%}
{%- set document_path = relative_path -%}
{%- if theme_source_edit_link -%}
{{ theme_source_edit_link.format(filename=pagename+page_source_suffix) }}
{%- else -%}
{%- set document_path = subdirectory + "/" + relative_path -%}
{%- endif -%}
{#- First, sanitise the trailing slashes. -#}
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
{%- set branch = theme_source_branch -%}
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}

{#- Don't allow http:// URLs -#}
{%- if repo.startswith(
(
"http://github.com/",
"http://gitlab.com/",
"http://bitbucket.org/",
)
) -%}
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
{#- Handle the relevant cases -#}
{%- elif repo.startswith("https://github.com/") -%}
{{ repo }}/edit/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://gitlab.com/") -%}
{{ repo }}/-/edit/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://bitbucket.org/") -%}
{{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }}
{#- Fail with a warning -#}
{%- else -%}
{{ warning("Could not understand `source_repository` provided: " + repo) }}
{#- Figure out the document's source file path. -#}
{%- set relative_path = pagename + page_source_suffix -%}
{%- if not subdirectory -%}
{%- set document_path = relative_path -%}
{%- else -%}
{%- set document_path = subdirectory + "/" + relative_path -%}
{%- endif -%}

{#- Don't allow http:// URLs -#}
{%- if repo.startswith(
(
"http://github.com/",
"http://gitlab.com/",
"http://bitbucket.org/",
)
) -%}
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
{#- Handle the relevant cases -#}
{%- elif repo.startswith("https://github.com/") -%}
{{ repo }}/edit/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://gitlab.com/") -%}
{{ repo }}/-/edit/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://bitbucket.org/") -%}
{{ repo }}/src/{{ branch }}/{{ document_path }}?mode=edit&at={{ branch }}
{#- Fail with a warning -#}
{%- else -%}
{{ warning(
"Could not understand `source_repository` provided: " + repo + "\n" +
"You should set `source_edit_link`, so that the edit link is presented."
) }}
{%- endif -%}
{%- endif -%}
{%- endmacro -%}


{%- if page_source_suffix -%}
{%- if theme_source_repository -%}
{%- if not theme_source_branch -%}
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
{%- endif -%}
{% block link_available %}
{%- set can_find_edit_link = (
(theme_source_edit_link and pagename)
or (theme_source_repository and theme_source_branch)
) -%}
{%- if can_find_edit_link -%}
{%- block link_available -%}
<a href="{{ determine_page_edit_link() }}">{{ _("Edit this page") }}</a>
{% endblock link_available %}
{%- endblock link_available -%}
{%- else -%}
{% block link_not_available %}{% endblock %}
{%- block link_not_available -%}{%- endblock -%}
{%- endif -%}
{%- endif -%}
89 changes: 51 additions & 38 deletions src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,63 @@
{%- macro sanitise_trailing_slash(s) -%}{{ s.rstrip("/") }}{%- endmacro -%}

{%- macro determine_page_view_link() -%}
{#- First, sanitise the trailing slashes. -#}
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
{%- set branch = theme_source_branch -%}
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}
{%- if theme_source_view_link -%}
{{ theme_source_view_link.format(filename=pagename+page_source_suffix) }}
{%- elif theme_source_repository -%}
{#- First, sanitise the trailing slashes. -#}
{%- set repo = sanitise_trailing_slash(theme_source_repository) -%}
{%- set branch = theme_source_branch -%}
{%- set subdirectory = sanitise_trailing_slash(theme_source_directory) -%}

{#- Figure out the document's source file path. -#}
{%- set relative_path = pagename + page_source_suffix -%}
{%- if not subdirectory -%}
{%- set document_path = relative_path -%}
{%- else -%}
{%- set document_path = subdirectory + "/" + relative_path -%}
{%- endif -%}
{#- Figure out the document's source file path. -#}
{%- set relative_path = pagename + page_source_suffix -%}
{%- if not subdirectory -%}
{%- set document_path = relative_path -%}
{%- else -%}
{%- set document_path = subdirectory + "/" + relative_path -%}
{%- endif -%}

{#- Don't allow http:// URLs -#}
{%- if repo.startswith(
(
"http://github.com/",
"http://gitlab.com/",
"http://bitbucket.org/",
)
) -%}
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
{#- Handle the relevant cases -#}
{%- elif repo.startswith("https://github.com/") -%}
{{ repo }}/blob/{{ branch }}/{{ document_path }}?plain=true
{%- elif repo.startswith("https://gitlab.com/") -%}
{{ repo }}/blob/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://bitbucket.org/") -%}
{{ repo }}/src/{{ branch }}/{{ document_path }}
{#- Fail with a warning -#}
{%- else -%}
{{ warning("Could not understand `source_repository` provided: " + repo) }}
{#- Don't allow http:// URLs -#}
{%- if repo.startswith(
(
"http://github.com/",
"http://gitlab.com/",
"http://bitbucket.org/",
)
) -%}
{{ warning("Could not use `source_repository` provided. Please use https:// links in your `conf.py` file's `html_theme_options`.") }}
{#- Handle the relevant cases -#}
{%- elif repo.startswith("https://github.com/") -%}
{{ repo }}/blob/{{ branch }}/{{ document_path }}?plain=true
{%- elif repo.startswith("https://gitlab.com/") -%}
{{ repo }}/blob/{{ branch }}/{{ document_path }}
{%- elif repo.startswith("https://bitbucket.org/") -%}
{{ repo }}/src/{{ branch }}/{{ document_path }}
{#- Fail with a warning -#}
{%- else -%}
{{ warning(
"Could not understand `source_repository` provided: " + repo + "\n" +
"You should set `source_view_link`, so that the view link is presented."
) }}
{%- endif -%}
{%- elif show_source and has_source -%}
{{ pathto('_sources/' + sourcename, true) }}
{%- endif -%}
{%- endif -%}
{%- endmacro -%}


{%- if page_source_suffix -%}
{%- if theme_source_repository -%}
{%- if not theme_source_branch -%}
{{ warning("Provided `source_repository` but not `source_branch`. ")}}
{%- endif -%}
{% block link_available %}
<a href="{{ determine_page_view_link() }}">{{ _("View this page") }}</a>
{% endblock link_available %}
{%- set can_find_view_link = (
(theme_source_view_link and pagename)
or (show_source and has_source and sourcename)
or (theme_source_repository and theme_source_branch)
) -%}
{%- if can_find_view_link -%}
{%- block link_available -%}
<a href="{{ determine_page_view_link() }}">{{ _("View sources") }}</a>
{%- endblock link_available -%}
{%- else -%}
{% block link_not_available %}{% endblock %}
{%- block link_not_available -%}{%- endblock -%}
{%- endif -%}
{%- endif -%}