From 801fb0c3d696aa86da386c985bc5d4e5bf713332 Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Sat, 2 Dec 2023 13:11:51 +0100
Subject: [PATCH] DOC: show how to overwrite repo-button.html

... and provide a few more icons.
---
 doc/configuration.rst                         |  5 ++-
 doc/customization.rst                         | 43 +++++++++++++------
 .../insipid/icons/code-branch.svg             |  1 +
 .../insipid/icons/git-alt.svg                 |  1 +
 .../insipid/icons/git.svg                     |  1 +
 5 files changed, 36 insertions(+), 15 deletions(-)
 create mode 120000 src/insipid_sphinx_theme/insipid/icons/code-branch.svg
 create mode 120000 src/insipid_sphinx_theme/insipid/icons/git-alt.svg
 create mode 120000 src/insipid_sphinx_theme/insipid/icons/git.svg

diff --git a/doc/configuration.rst b/doc/configuration.rst
index 2fea946..b751268 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -120,6 +120,9 @@ See below for `default values`_.
             if the repository containing your source files is
             hosted on Bitbucket or Github, respectively.
 
+            If you use a different hosting platform,
+            you can :ref:`override this template entirely <repo-button-html>`.
+
     :gh-template:`pdf-button.html`
         A link to the PDF version of your docs.
 
@@ -220,7 +223,7 @@ __ https://github.com/sphinx-doc/sphinx/blob/master/
 
 
 .. theme-option:: body_max_width
-    
+
     Maximal width of the main document text (in pixels or any CSS unit).
     Set it to ``None`` for unlimited width.
 
diff --git a/doc/customization.rst b/doc/customization.rst
index 76079c0..f87a86d 100644
--- a/doc/customization.rst
+++ b/doc/customization.rst
@@ -50,7 +50,35 @@ You can create arbitrary new files and add them to those lists.
 You can also extend (or completely replace) existing templates
 (:gh-template:`layout.html`, :gh-template:`page.html`,
 :gh-template:`footer.html` etc.).
-For example, you can extend the template :gh-template:`layout.html`
+
+For example, if Sphinx's :confval:`copyright` setting is not flexible enough
+(because it inserts a "copyright" symbol which may not be desired),
+one could create a customized note by replacing the existing template
+:gh-template:`copyright.html`:
+
+.. code-block:: html+jinja
+    :name: copyright-html
+    :caption: :file:`_templates/copyright.html`
+
+    Dedicated to the public domain with
+    <a href="https://creativecommons.org/publicdomain/zero/1.0/"
+       class="reference external">CC0 1.0</a>.
+
+As another example,
+if you don't use Bitbucket/Gitlab/Github for hosting your project,
+you can overwrite the :gh-template:`repo-button.html` template
+to use a custom URL and icon:
+
+.. code-block:: html+jinja
+    :name: repo-button-html
+    :caption: :file:`_templates/repo-button.html`
+
+    <a href="https://example.org/user/repo/" title="My Hosting">
+      {% include 'icons/code-branch.svg' %}
+    </a>
+
+To give yet another example,
+you can also extend the template :gh-template:`layout.html`
 by creating your own file named :file:`layout.html`:
 
 .. code-block:: html+jinja
@@ -86,19 +114,6 @@ If you don't use the ``extends`` tag,
 you can completely replace a given template.
 By leaving the file empty, you can disable a template.
 
-For example, if the setting :confval:`copyright` is not flexible enough
-(because it inserts a "copyright" symbol which may not be desired),
-one could create a customized note by replacing the existing template
-:gh-template:`copyright.html`:
-
-.. code-block:: html+jinja
-    :name: copyright-html
-    :caption: :file:`_templates/copyright.html`
-
-    Dedicated to the public domain with
-    <a href="https://creativecommons.org/publicdomain/zero/1.0/"
-       class="reference external">CC0 1.0</a>.
-
 For further information, see :ref:`sphinx:templating`.
 
 
diff --git a/src/insipid_sphinx_theme/insipid/icons/code-branch.svg b/src/insipid_sphinx_theme/insipid/icons/code-branch.svg
new file mode 120000
index 0000000..16ebbb2
--- /dev/null
+++ b/src/insipid_sphinx_theme/insipid/icons/code-branch.svg
@@ -0,0 +1 @@
+../../../../Font-Awesome/svgs/solid/code-branch.svg
\ No newline at end of file
diff --git a/src/insipid_sphinx_theme/insipid/icons/git-alt.svg b/src/insipid_sphinx_theme/insipid/icons/git-alt.svg
new file mode 120000
index 0000000..fa711d6
--- /dev/null
+++ b/src/insipid_sphinx_theme/insipid/icons/git-alt.svg
@@ -0,0 +1 @@
+../../../../Font-Awesome/svgs/brands/git-alt.svg
\ No newline at end of file
diff --git a/src/insipid_sphinx_theme/insipid/icons/git.svg b/src/insipid_sphinx_theme/insipid/icons/git.svg
new file mode 120000
index 0000000..7d8748f
--- /dev/null
+++ b/src/insipid_sphinx_theme/insipid/icons/git.svg
@@ -0,0 +1 @@
+../../../../Font-Awesome/svgs/brands/git.svg
\ No newline at end of file