diff --git a/docs/customisation/edit-button.md b/docs/customisation/edit-button.md index dc7749a4..368a7e5c 100644 --- 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 index 61edf0f5..aa83c166 100644 --- 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 new file mode 100644 index 00000000..67ac2123 --- /dev/null +++ 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 index 0e4af5db..35f2fb22 100644 --- 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 index 18790fc0..6551aa04 100644 --- 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 index 1a63ff49..f913f64b 100644 --- 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) -%}
- +
@@ -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 new file mode 100644 index 00000000..bd00f035 --- /dev/null +++ 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) -%} +
+ + + + +
+{%- 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 index 34648fd7..fc81d4eb 100644 --- a/src/furo/theme/furo/page.html +++ b/src/furo/theme/furo/page.html @@ -75,11 +75,32 @@ {% trans %}Back to top{% endtrans %}
- {% 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 -#}