Add a view this page button

pradyunsg · May 6, 2024 · 2ce7e89 · 2ce7e89
1 parent 74a63c5
commit 2ce7e89
Show file tree

Hide file tree

Showing 10 changed files with 148 additions and 69 deletions.
diff --git a/docs/customisation/edit-button.md b/docs/customisation/edit-button.md
@@ -1,47 +1,7 @@
-# Adding an edit button
-
-Furo can add a small edit button to each document to allow visitors to easily propose changes to that document using the repository's source control system.
-
-## With popular VCS hosts
-
-Provide the relevant VCS variables, by setting the following keys in [`html_theme_options`][sphinx-html_theme_options]:
-
-```python
-html_theme_options = {
-    "source_repository": "https://github.com/pradyunsg/furo/",
-    "source_branch": "main",
-    "source_directory": "docs/",
-}
-```
-
-This model supports github.com, gitlab.com and bitbucket.org as domain names for the `source_repository` key.
-
-## With arbitrary URLs
-
-```{versionadded} 2022.09.29
-
-```
+---
+orphan: true
+---
 
-Use arbitrary URLs for the edit button, by setting the following key in [`html_theme_options`][sphinx-html_theme_options]:
-
-```python
-html_theme_options = {
-    "source_edit_link": "https://my.awesome.host.example.com/awesome/project/edit/{filename}",
-}
-```
-
-The `{filename}` component will be replaced with the full path to the file, as known from the base of the documentation directory.
-
-```{important}
-Furo does not enforce that the `source_edit_link` contains `{filename}` or any sort of correctness check on this URL. Make sure to manually confirm that the link works.
-```
-
-## Read the Docs support
-
-If you're building documentation on Read the Docs using a github.com-hosted repository as the source, the edit button is enabled by default.
-
-### Disabling on Read the Docs
-
-If you wish to disable this, use {ref}`top_of_page_button` and set it to `None`.
+# Adding an edit button
 
-[sphinx-html_theme_options]: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme_options
+This page has been replaced with {doc}`./top-of-page-buttons`.
diff --git a/docs/customisation/index.md b/docs/customisation/index.md
@@ -9,7 +9,7 @@ This section serves to guide the user with customising Furo-based documentation.
 
 logo
 announcement
-edit-button
+top-of-page-buttons
 colors
 fonts
 footer
@@ -74,7 +74,7 @@ html_theme_options = {
 
 (top_of_page_button)=
 
-### `top_of_page_button`
+### `top_of_page_button` (deprecated, due to be removed after 2024-11-01)
 
 Controls which button is shown on the top of the page. The only supported values are `"edit"` (the default) and `None`.
 
@@ -84,6 +84,21 @@ html_theme_options = {
 }
 ```
 
+(top_of_page_buttons)=
+
+### `top_of_page_buttons`
+
+Controls which buttons are shown on the top of the page. This is a list which can be empty or contain one-or-more of the following values:
+
+- `"edit"`
+- `"view"`
+
+```python
+html_theme_options = {
+    "top_of_page_buttons": ["view", "edit"],
+}
+```
+
 ### `announcement`
 
 Add a site-wide announcement, to the top of every page when set. See {doc}`./announcement` for the details.

diff --git a/docs/customisation/top-of-page-buttons.md b/docs/customisation/top-of-page-buttons.md
@@ -0,0 +1,58 @@
+# Adding source code buttons
+
+```{versionadded} 2024.05.06
+Support for "view this page" link.
+```
+
+Furo can add buttons to each document that links visitors to the document's sources on the repository's source control system.
+
+This feature is inherited from [sphinx-basic-ng](https://sphinx-basic-ng.readthedocs.io/en/latest/), specifically the [`view-this-page.html`](https://sphinx-basic-ng.readthedocs.io/en/latest/usage/components/view-this-page/) and [`edit-this-page`](https://sphinx-basic-ng.readthedocs.io/en/latest/usage/components/edit-this-page/) components.
+
+## With popular VCS hosts
+
+Provide the relevant VCS variables, by setting the following keys in [`html_theme_options`][sphinx-html_theme_options]:
+
+```python
+html_theme_options = {
+    "source_repository": "https://github.com/pradyunsg/furo/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+```
+
+This model supports github.com, gitlab.com and bitbucket.org as domain names for the `source_repository` key.
+
+## With arbitrary URLs
+
+```{versionadded} 2022.09.29
+
+```
+
+Use arbitrary URLs for the view/edit buttons, by setting the following keys in [`html_theme_options`][sphinx-html_theme_options]:
+
+```python
+html_theme_options = {
+    "source_edit_link": "https://my.awesome.host.example.com/awesome/project/edit/{filename}",
+    "source_view_link": "https://my.awesome.host.example.com/awesome/project/view/{filename}",
+}
+```
+
+The `{filename}` component will be replaced with the full path to the file, as known from the base of the documentation directory.
+
+```{important}
+Furo does not enforce that the `source_edit_link` / `source_view_link` contain `{filename}` or any sort of correctness check on these URLs. Make sure to manually confirm that the link works.
+```
+
+## Read the Docs support
+
+```{versionchanged} 2024.05.06
+This feature has been tentatively removed (but the removal has not been released), as a better approach is investigated. See [this discussion](https://github.com/pradyunsg/furo/discussions/785) for more details.
+```
+
+If you're building documentation on Read the Docs using a github.com-hosted repository as the source, the edit button is enabled by default.
+
+### Disabling on Read the Docs
+
+If you wish to disable this, use {ref}`top_of_page_button` and set it to `None`.
+
+[sphinx-html_theme_options]: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme_options
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ requires-python = ">=3.8"
 dependencies = [
   "beautifulsoup4",
   "sphinx >= 6.0,<8.0",
-  "sphinx-basic-ng",
+  "sphinx-basic-ng >= 1.0.0.beta2",
   "pygments >= 2.7",
 ]
 

diff --git a/src/furo/assets/styles/_scaffold.sass b/src/furo/assets/styles/_scaffold.sass
@@ -243,10 +243,11 @@ article
   margin-bottom: 1rem
   gap: 0.5rem
 
-  .edit-this-page svg
-    color: inherit
-    height: $icon-size
-    width: $icon-size
+  .edit-this-page, .view-this-page
+    svg
+      color: inherit
+      height: $icon-size
+      width: $icon-size
 
 .sidebar-toggle
   position: absolute

diff --git a/src/furo/theme/furo/components/edit-this-page.html b/src/furo/theme/furo/components/edit-this-page.html
@@ -4,11 +4,7 @@
 {%- macro furo_edit_button(url) -%}
 <div class="edit-this-page">
   <a class="muted-link" href="{{ url }}" title="{{ _("Edit this page") }}">
-    <svg aria-hidden="true" viewBox="0 0 24 24" stroke-width="1" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-      <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
-      <path d="M4 20h4l10.5 -10.5a1.5 1.5 0 0 0 -4 -4l-10.5 10.5v4" />
-      <line x1="13.5" y1="6.5" x2="17.5" y2="10.5" />
-    </svg>
+    <svg><use href="#svg-pencil"></use></svg>
     <span class="visually-hidden">{{ _("Edit this page") }}</span>
   </a>
 </div>
@@ -17,11 +13,3 @@
 {% block link_available -%}
 {{ furo_edit_button(determine_page_edit_link()) }}
 {%- endblock %}
-
-{% block link_not_available %}
-{# Make nice things happen, on Read the Docs #}
-{%- if READTHEDOCS and conf_py_path and page_source_suffix and github_user != "None" and github_repo != "None" and github_version and pagename and page_source_suffix %}
-  {% set url = "https://github.com/" + github_user + "/" + github_repo + "/edit/" + github_version + conf_py_path + pagename + page_source_suffix %}
-  {{ furo_edit_button(url) }}
-{%- endif -%}
-{% endblock %}
diff --git a/src/furo/theme/furo/components/view-this-page.html b/src/furo/theme/furo/components/view-this-page.html
@@ -0,0 +1,15 @@
+{% extends "basic-ng/components/view-this-page.html" %}
+{% from "basic-ng/components/view-this-page.html" import determine_page_view_link with context %}
+
+{%- macro furo_view_button(url) -%}
+<div class="view-this-page">
+  <a class="muted-link" href="{{ url }}" title="{{ _("View this page") }}">
+    <svg><use href="#svg-eye"></use></svg>
+    <span class="visually-hidden">{{ _("View this page") }}</span>
+  </a>
+</div>
+{%- endmacro -%}
+
+{% block link_available -%}
+{{ furo_view_button(determine_page_view_link()) }}
+{%- endblock %}
diff --git a/src/furo/theme/furo/page.html b/src/furo/theme/furo/page.html
@@ -75,11 +75,32 @@
           <span>{% trans %}Back to top{% endtrans %}</span>
         </a>
         <div class="content-icon-container">
-          {% if theme_top_of_page_button == "edit" -%}
-          {%- include "components/edit-this-page.html" with context -%}
-          {%- elif theme_top_of_page_button != None -%}
-          {{ warning("Got an unsupported value for 'top_of_page_button'") }}
+          {% if theme_top_of_page_button != "edit" -%}
+            {{ warning("Got configuration for 'top_of_page_button': this is deprecated.") }}
           {%- endif -%}
+
+          {%- if theme_top_of_page_buttons == "" -%}
+            {% if theme_top_of_page_button == None -%}
+              {#- We respect the old configuration of disabling all the buttons -#}
+              {%- set theme_top_of_page_buttons = [] -%}
+            {% else %}
+              {%- set theme_top_of_page_buttons = ["view", "edit"] -%}
+            {%- endif -%}
+          {% else -%}
+            {% if theme_top_of_page_button != "edit" -%}
+              {%- set theme_top_of_page_buttons = [] -%}
+              {{ warning("Got configuration for both 'top_of_page_button' and 'top_of_page_buttons', ignoring both and removing all top of page buttons.") }}
+            {%- endif -%}
+          {%- endif -%}
+          {% for button in theme_top_of_page_buttons -%}
+            {% if button == "view" %}
+            {%- include "components/view-this-page.html" with context -%}
+            {% elif button == "edit" %}
+            {%- include "components/edit-this-page.html" with context -%}
+            {% else %}
+            {{ warning("Got an unsupported value in 'top_of_page_buttons' for theme configuration") }}
+            {% endif %}
+          {%- endfor -%}
           {#- Theme toggle -#}
           <div class="theme-toggle-container theme-toggle-content">
             <button class="theme-toggle">

diff --git a/src/furo/theme/furo/partials/icons.html b/src/furo/theme/furo/partials/icons.html
@@ -92,4 +92,24 @@
       <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
     </svg>
   </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" /
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
 </svg>
diff --git a/src/furo/theme/furo/theme.conf b/src/furo/theme/furo/theme.conf
@@ -22,6 +22,7 @@ light_logo =
 sidebar_hide_name =
 footer_icons =
 top_of_page_button = edit
+top_of_page_buttons =
 # For components/edit-this-page.html
 source_repository =
 source_branch =