From f95ea65d86660999b770a9f3337614e389386fb8 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 10 Jul 2022 12:03:09 +0100 Subject: [PATCH 1/3] Add user-provided overrides for edit and view links This allows for users to depend on these keys. --- docs/usage/components/edit-this-page.md | 39 ++++----- docs/usage/components/view-this-page.md | 35 ++++---- .../basic-ng/components/edit-this-page.html | 83 ++++++++++-------- .../basic-ng/components/view-this-page.html | 85 ++++++++++--------- 4 files changed, 131 insertions(+), 111 deletions(-) diff --git a/docs/usage/components/edit-this-page.md b/docs/usage/components/edit-this-page.md index 507e40c..a6de7c7 100644 --- a/docs/usage/components/edit-this-page.md +++ b/docs/usage/components/edit-this-page.md @@ -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 = @@ -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, @@ -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 }}" %} - {{ _("Edit this page") }} - {%- elif theme_source_repository -%} - {%- if not theme_source_branch -%} - {{ warning("Provided `source_repository` but not `source_branch`. ")}} - {%- endif -%} - {{ _("Edit this page") }} - {%- endif -%} - {%- endif -%} + {{ _("Edit this page") }} ``` diff --git a/docs/usage/components/view-this-page.md b/docs/usage/components/view-this-page.md index 315d796..12dd520 100644 --- a/docs/usage/components/view-this-page.md +++ b/docs/usage/components/view-this-page.md @@ -16,6 +16,7 @@ This will add a single `a[href]` tag, with the text "View this page". You also need to declare the following in `theme.conf`'s `options` section: ```ini +source_view_link = source_repository = source_branch = source_directory = @@ -34,6 +35,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/`. @@ -59,26 +69,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 }}" %} - {{ _("View this page") }} - {%- elif theme_source_repository -%} - {%- if not theme_source_branch -%} - {{ warning("Provided `source_repository` but not `source_branch`. ")}} - {%- endif -%} - {{ _("View this page") }} - {%- endif -%} - {%- endif -%} + {{ _("View this page") }} ``` diff --git a/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html b/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html index be8d088..ff30468 100644 --- a/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html +++ b/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html @@ -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 + or (theme_source_repository and theme_source_branch) + ) -%} + {%- if can_find_edit_link -%} + {%- block link_available -%} {{ _("Edit this page") }} - {% endblock link_available %} + {%- endblock link_available -%} {%- else -%} - {% block link_not_available %}{% endblock %} + {%- block link_not_available -%}{%- endblock -%} {%- endif -%} {%- endif -%} diff --git a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html index 8e20489..92a5536 100644 --- a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html +++ b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html @@ -1,50 +1,59 @@ {%- 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) -%} - - {#- 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_view_link -%} + {{ theme_source_view_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 }}/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) }} + {#- 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 + "\n" + + "You should set `source_view_link`, so that the view 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 %} - {{ _("View this page") }} - {% endblock link_available %} + {%- set can_find_view_link = ( + theme_source_view_link + or (theme_source_repository and theme_source_branch) + ) -%} + {%- if can_find_view_link -%} + {%- block link_available -%} + {{ _("View sources") }} + {%- endblock link_available -%} {%- else -%} - {% block link_not_available %}{% endblock %} + {%- block link_not_available -%}{%- endblock -%} {%- endif -%} {%- endif -%} From 94375878e957b303467a990a9335e22c1532177d Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 10 Jul 2022 12:08:11 +0100 Subject: [PATCH 2/3] Make `view-this-page` fall-back to Sphinx's copied sources This surfaces the files copied by Sphinx, if they're supposed to be shown according to the configuration. --- docs/usage/components/view-this-page.md | 5 +++++ .../theme/basic-ng/components/view-this-page.html | 6 +++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/usage/components/view-this-page.md b/docs/usage/components/view-this-page.md index 12dd520..27622f7 100644 --- a/docs/usage/components/view-this-page.md +++ b/docs/usage/components/view-this-page.md @@ -13,6 +13,11 @@ 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 diff --git a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html index 92a5536..bf7e9d2 100644 --- a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html +++ b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html @@ -3,7 +3,7 @@ {%- macro determine_page_view_link() -%} {%- if theme_source_view_link -%} {{ theme_source_view_link.format(filename=pagename+page_source_suffix) }} - {%- else -%} + {%- elif theme_source_repository -%} {#- First, sanitise the trailing slashes. -#} {%- set repo = sanitise_trailing_slash(theme_source_repository) -%} {%- set branch = theme_source_branch -%} @@ -40,6 +40,9 @@ "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 -%} @@ -47,6 +50,7 @@ {%- if page_source_suffix -%} {%- set can_find_view_link = ( theme_source_view_link + or (show_source and has_source and sourcename) or (theme_source_repository and theme_source_branch) ) -%} {%- if can_find_view_link -%} From 7a441a9c16e90e937450c4ea0bb2262bd5ce6f71 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 10 Jul 2022 12:14:43 +0100 Subject: [PATCH 3/3] Only use `source_{view,edit}_link` on pages with `pagename` This ensures pages that don't have a corresponding file won't get rendered via this theme. --- .../theme/basic-ng/components/edit-this-page.html | 2 +- .../theme/basic-ng/components/view-this-page.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html b/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html index ff30468..67f1a9b 100644 --- a/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html +++ b/src/sphinx_basic_ng/theme/basic-ng/components/edit-this-page.html @@ -46,7 +46,7 @@ {%- if page_source_suffix -%} {%- set can_find_edit_link = ( - theme_source_edit_link + (theme_source_edit_link and pagename) or (theme_source_repository and theme_source_branch) ) -%} {%- if can_find_edit_link -%} diff --git a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html index bf7e9d2..562fb2d 100644 --- a/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html +++ b/src/sphinx_basic_ng/theme/basic-ng/components/view-this-page.html @@ -49,7 +49,7 @@ {%- if page_source_suffix -%} {%- set can_find_view_link = ( - theme_source_view_link + (theme_source_view_link and pagename) or (show_source and has_source and sourcename) or (theme_source_repository and theme_source_branch) ) -%}