Skip to content

Commit

Permalink
DOC: show how to overwrite repo-button.html
Browse files Browse the repository at this point in the history
... and provide a few more icons.
  • Loading branch information
mgeier committed Dec 2, 2023
1 parent 61a7da2 commit 801fb0c
Show file tree
Hide file tree
Showing 5 changed files with 36 additions and 15 deletions.
5 changes: 4 additions & 1 deletion doc/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
43 changes: 29 additions & 14 deletions doc/customization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`.


Expand Down
1 change: 1 addition & 0 deletions src/insipid_sphinx_theme/insipid/icons/code-branch.svg
1 change: 1 addition & 0 deletions src/insipid_sphinx_theme/insipid/icons/git-alt.svg
1 change: 1 addition & 0 deletions src/insipid_sphinx_theme/insipid/icons/git.svg

0 comments on commit 801fb0c

Please sign in to comment.