-
Notifications
You must be signed in to change notification settings - Fork 317
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Making navbar + a few other sections more modular (#355)
Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>
- Loading branch information
1 parent
3532922
commit f1e4d91
Showing
28 changed files
with
388 additions
and
111 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
v{{ version }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -8,4 +8,5 @@ User Guide | |
|
||
install | ||
configuring | ||
sections | ||
customizing |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,146 @@ | ||
==================================== | ||
Add/Remove items from theme sections | ||
==================================== | ||
|
||
There are a few major theme sections that you can customize to add/remove | ||
components, or add your own components. Each section is configured with a | ||
list of *html templates* - these are snippets of HTML that are inserted into | ||
the section by Sphinx. | ||
|
||
You can choose which templates show up in each section, as well as the order in | ||
which they appear. This page describes the major areas that you can customize. | ||
|
||
.. note:: | ||
|
||
When configuring templates in each section, you may omit the ``.html`` | ||
suffix after each template if you wish. | ||
|
||
The navbar items | ||
================ | ||
|
||
The navbar is at the top of the page, and is broken up into three sections. | ||
Each section is configured in ``conf.py`` with the following configuration: | ||
|
||
- Left section: ``html_theme_options['navbar_start']`` | ||
- Middle menu: ``html_theme_options['navbar_center']`` | ||
- Right section: ``html_theme_options['navbar_end']`` | ||
|
||
By default, the following configuration is used: | ||
|
||
.. code-block:: python | ||
html_theme_options = { | ||
... | ||
"navbar_start": ["navbar-logo"], | ||
"navbar_center": ["navbar-nav"], | ||
"navbar_end": ["navbar-icon-links"] | ||
... | ||
} | ||
The left sidebar | ||
================ | ||
|
||
The left sidebar is just to the left of a page's main content. | ||
Configuring it is a bit different from configuring the other sections, because | ||
configuring the sidebar is natively supported in Sphinx, via the ``html_sidebars`` | ||
configuration variable. | ||
|
||
For the left sidebar only, you can configure templates so that they only show | ||
up on certain pages. You do so via a configuration like so in ``conf.py``: | ||
|
||
.. code-block:: python | ||
html_sidebars = { | ||
"<page_pattern>": ["list", "of", "templates"] | ||
} | ||
Any pages that match ``<page_pattern>`` will have their respective templates | ||
inserted. You can also ``*`` to do ``glob``-style matching, and may use ``**`` | ||
to match all pages. | ||
|
||
By default, it has the following configuration: | ||
|
||
.. code-block:: python | ||
html_sidebars = { | ||
"**": ["search-field", "sidebar-nav-bs", "sidebar-ethical-ads"] | ||
} | ||
The right in-page sidebar | ||
========================= | ||
|
||
The in-page sidebar is just to the right of a page's main content, and is | ||
configured in ``conf.py`` with ``html_theme_options['page_sidebar_items']``. | ||
|
||
By default, it has the following templates: | ||
|
||
.. code-block:: python | ||
html_theme_options = { | ||
... | ||
"page_sidebar_items": ["page-toc", "edit-this-page"], | ||
... | ||
} | ||
The footer | ||
========== | ||
|
||
The footer is just below a page's main content, and is configured in ``conf.py`` | ||
with ``html_theme_options['footer_items']``. | ||
|
||
By default, it has the following templates: | ||
|
||
.. code-block:: python | ||
html_theme_options = { | ||
... | ||
"footer_items": ["copyright", "sphinx-version"], | ||
... | ||
} | ||
A list of built-in templates you can insert into sections | ||
========================================================= | ||
|
||
Below is a list of build-in templates that you can insert into any section. | ||
Note that some of them may have CSS rules that assume a specific section (and | ||
will be named accordingly). | ||
|
||
- ``icon-links.html`` | ||
- ``search-field.html`` | ||
- ``copyright.html`` | ||
- ``edit-this-page.html`` | ||
- ``last-updated.html`` | ||
- ``navbar-icon-links.html`` | ||
- ``navbar-logo.html`` | ||
- ``navbar-nav.html`` | ||
- ``page-toc.html`` | ||
- ``sidebar-ethical-ads.html`` | ||
- ``sidebar-nav-bs.html`` | ||
- ``sphinx-version.html`` | ||
|
||
Add your own HTML templates to theme sections | ||
============================================= | ||
|
||
If you'd like to add your own custom template to any of these sections, you | ||
could do so with the following steps: | ||
|
||
1. Create an HTML file in a folder called ``_templates``. For example, if | ||
you wanted to display the version of your documentation using a Jinja | ||
template, you could create a file: ``_templates/version.html`` and put the | ||
following in it: | ||
|
||
.. code-block:: html | ||
|
||
<!-- This will display the version of the docs --> | ||
{{ version }} | ||
|
||
1. Now add the file to your menu items for one of the sections above. For example: | ||
|
||
.. code-block:: python | ||
html_theme_options = { | ||
... | ||
"navbar_start": ["navbar-logo", "version"], | ||
... | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
<p class="copyright"> | ||
{%- if hasdoc('copyright') %} | ||
{% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/> | ||
{%- else %} | ||
{% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %}<br/> | ||
{%- endif %} | ||
</p> |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
<p class="last-updated"> | ||
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/> | ||
</p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
{%- block icon_links -%} | ||
{%- include "icon-links.html" with context -%} | ||
{%- endblock %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
{% if logo %} | ||
{% if not theme_logo_link %} | ||
<a class="navbar-brand" href="{{ pathto(master_doc) }}"> | ||
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"> | ||
</a> | ||
{% elif theme_logo_link[:4] == 'http' %} | ||
<a class="navbar-brand" href="{{ theme_logo_link }}"> | ||
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"> | ||
</a> | ||
{% else %} | ||
<a class="navbar-brand" href="{{ pathto(theme_logo_link) }}"> | ||
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo"> | ||
</a> | ||
{% endif %} | ||
{% else %} | ||
<a class="navbar-brand" href="{{ pathto(master_doc) }}"> | ||
<p class="title">{{ project }}</p> | ||
</a> | ||
{% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
<ul id="navbar-main-elements" class="navbar-nav"> | ||
{{ generate_nav_html("navbar", maxdepth=1, collapse=True, includehidden=True, titles_only=True) }} | ||
{% for external_link in theme_external_links %} | ||
<li class="nav-item"> | ||
<a class="nav-link nav-external" href="{{ external_link.url }}">{{ external_link.name }}<i class="fas fa-external-link-alt"></i></a> | ||
</li> | ||
{% endfor %} | ||
</ul> |
Oops, something went wrong.