From 801fb0c3d696aa86da386c985bc5d4e5bf713332 Mon Sep 17 00:00:00 2001 From: Matthias Geier 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 `. + :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 + CC0 1.0. + +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` + + + {% include 'icons/code-branch.svg' %} + + +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 - CC0 1.0. - 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