IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into Blendify/python-compat

Browse Source
This commit is contained in:
Aaron Carlisle
2021-06-22 18:47:00 -04:00
committed by GitHub
parent 60a094bb13 71d6d182cf
commit b2323ce07f
12 changed files with 134 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.rst
View File

@@ -33,21 +33,15 @@ This theme is distributed on PyPI_ and can be installed with ``pip``:
$ pip install sphinx-rtd-theme
To use the theme in your Sphinx project, you will need to add the following to
your ``conf.py`` file:
To use the theme in your Sphinx project, you will need to edit
your ``conf.py`` file's ``html_theme`` setting:
.. code:: python
import sphinx_rtd_theme
extensions = [
...
"sphinx_rtd_theme",
]
html_theme = "sphinx_rtd_theme"
For more information read the full documentation on `installing the theme`_
For more information, including a full example with localized strings enabled,
read the documentation on `installing the theme`_.
.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
.. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html

6
docs/conf.py
View File

@@ -10,12 +10,14 @@ sys.path.insert(0, os.path.abspath('..'))
sys.path.append(os.path.abspath('./demo/'))
import sphinx_rtd_theme
from sphinx_rtd_theme import __version__ as theme_version
from sphinx_rtd_theme import __version_full__ as theme_version_full
from sphinx.locale import _
project = u'Read the Docs Sphinx Theme'
slug = re.sub(r'\W+', '-', project.lower())
version = '0.5.1'
release = '0.5.1'
version = theme_version
release = theme_version_full
author = u'Dave Snider, Read the Docs, Inc. & contributors'
copyright = author
language = 'en'

8
docs/configuring.rst
View File

@@ -13,7 +13,7 @@ For example:
.. code:: python
html_theme_options = {
'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard
'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard
'analytics_anonymize_ip': False,
'logo_only': False,
'display_version': True,
@@ -96,11 +96,13 @@ Miscellaneous options
.. confval:: analytics_id
If specified, Google Analytics' javascript is included in your pages.
Set the value to the ID provided to you by google (like ``UA-XXXXXXX``).
If specified, Google Analytics' `gtag.js`_ is included in your pages.
Set the value to the ID provided to you by google (like ``UA-XXXXXXX`` or ``G-XXXXXXXXXX``).
:type: string
.. _gtag.js: https://developers.google.com/gtagjs
.. confval:: analytics_anonymize_ip
Anonymize visitor IP addresses in Google Analytics.

2
setup.cfg
View File

@@ -1,5 +1,5 @@
[bumpversion]
current_version = 0.5.1
current_version = 0.5.2
commit = false
tag = false
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)((?P<release>[a-z]+)(?P<dev>\d+))?

8
sphinx_rtd_theme/__init__.py
View File

@@ -12,7 +12,7 @@ from sphinx.locale import _
from sphinx.util.logging import getLogger
__version__ = '0.5.1'
__version__ = '0.5.2'
__version_full__ = __version__
logger = getLogger(__name__)
@@ -55,4 +55,10 @@ def setup(app):
app.add_message_catalog('sphinx', rtd_locale_path)
app.connect('config-inited', config_initiated)
# sphinx emits the permalink icon for headers, so choose one more in keeping with our theme
if sphinx_version >= (3, 5, 0):
app.config.html_permalinks_icon = "\uf0c1"
else:
app.config.html_add_permalinks = "\uf0c1"
return {'parallel_read_safe': True, 'parallel_write_safe': True}

28
sphinx_rtd_theme/layout.html
View File

@@ -57,12 +57,12 @@
{%- if not embedded %}
{# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
{%- if sphinx_version >= "1.8.0" -%}
<script type="text/javascript" id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
<script id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
{%- for scriptfile in script_files %}
{{ js_tag(scriptfile) }}
{%- endfor %}
{%- else %}
<script type="text/javascript">
<script>
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'{{ url_root }}',
VERSION:'{{ release|e }}',
@@ -74,10 +74,10 @@
};
</script>
{%- for scriptfile in script_files %}
<script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
<script src="{{ pathto(scriptfile, 1) }}"></script>
{%- endfor %}
{%- endif %}
<script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
<script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
{#- OPENSEARCH #}
{%- if use_opensearch %}
@@ -174,7 +174,7 @@
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
{#- MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
<nav class="wy-nav-top" aria-label="{{ _('Top') }}">
<nav class="wy-nav-top" aria-label="{{ _('Top') }}" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
{%- block mobile_nav %}
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="{{ pathto(master_doc) }}">{{ project }}</a>
@@ -209,7 +209,7 @@
</div>
{% include "versions.html" -%}
<script type="text/javascript">
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable({{ 'true' if theme_sticky_navigation|tobool else 'false' }});
});
@@ -219,17 +219,15 @@
{%- if not READTHEDOCS %}
{%- if theme_analytics_id %}
<!-- Theme Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id={{ theme_analytics_id }}"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
ga('create', '{{ theme_analytics_id }}', 'auto');
{%- if theme_analytics_anonymize_ip|tobool %}
ga('set', 'anonymizeIp', true);
{%- endif %}
ga('send', 'pageview');
gtag('config', '{{ theme_analytics_id }}', {
'anonymize_ip': {{ 'true' if theme_analytics_anonymize_ip|tobool else 'false' }},
});
</script>
{%- endif %}

8
sphinx_rtd_theme/search.html
View File

@@ -12,16 +12,16 @@
{% set display_vcs_links = False %}
{%- block scripts %}
{{ super() }}
<script type="text/javascript" src="{{ pathto('_static/searchtools.js', 1) }}"></script>
<script type="text/javascript" src="{{ pathto('_static/language_data.js', 1) }}"></script>
<script src="{{ pathto('_static/searchtools.js', 1) }}"></script>
<script src="{{ pathto('_static/language_data.js', 1) }}"></script>
{%- endblock %}
{% block footer %}
<script type="text/javascript">
<script>
jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });
</script>
{# this is used when loading the search index using $.ajax fails,
such as on Chrome for documents on localhost #}
<script type="text/javascript" id="searchindexloader"></script>
<script id="searchindexloader"></script>
{{ super() }}
{% endblock %}
{% block body %}

2
src/sass/_theme_badge_fa.sass
View File

@@ -30,7 +30,7 @@ ul.fas
text-indent: -0.8em
li
.fa
width: .8em
width: 0.8em
.fa-large:before,
.fa-large:before
/* 1.5 increased font size for fa-large * 1.25 width

57
src/sass/_theme_layout.sass
View File

@@ -15,7 +15,7 @@ html
ul, li
display: inline-block
li:hover
background: rgba(255,255,255,.1)
background: rgba(255, 255, 255, 0.1)
li
&.divide-left
border-left: solid 1px hsl(0, 0%, 25%)
@@ -35,7 +35,7 @@ html
height: $base-font-size * 2
line-height: $base-font-size * 2
padding: 0 $gutter
margin: $base-line-height / 2 0 0 0
margin: ($base-line-height / 2) 0 0 0
display: block
font-weight: bold
text-transform: uppercase
@@ -54,7 +54,7 @@ html
a
color: $menu-link-medium
border-right: solid 1px darken($menu-vertical-background-color, 20%)
padding: $gutter / 4 $gutter * 1.5
padding: ($gutter / 4) ($gutter * 1.5)
&:hover
background: darken($menu-vertical-background-color, 15%)
code
@@ -64,7 +64,7 @@ html
padding-left: 0
padding-right: 0
// Expand links
span.toctree-expand
button.toctree-expand
display: block
float: left
margin-left: -1.2em
@@ -72,11 +72,14 @@ html
@extend .fa-plus-square-o
line-height: 18px
color: darken($menu-link-medium, 20%)
border: none
background: none
padding: 0
// On state for the first level
li.on a, li.current > a
color: $menu-link-color
padding: $gutter / 4 $gutter
padding: ($gutter / 4) $gutter
font-weight: bold
position: relative
background: $menu-vertical-background-color
@@ -85,9 +88,9 @@ html
+font-smooth
&:hover
background: $menu-vertical-background-color
span.toctree-expand
button.toctree-expand
color: $menu-link-medium
span.toctree-expand
button.toctree-expand
@extend .fa
@extend .fa-minus-square-o
display: block
@@ -107,7 +110,7 @@ html
display: block
%shrink_toctree_element
font-size: .9em
font-size: 0.9em
%toctree_link_color
color: $menu-link-color
@@ -128,13 +131,13 @@ html
@extend %toctree_link_color
&.current
> a
padding: $gutter / 4 $gutter * ($toc_level - 1 + .5)
padding: ($gutter / 4) ($gutter * ($toc_level - 1 + 0.5))
li.toctree-l#{$toc_level + 1} > a
@extend %display_current_toctree_element
padding: $gutter / 4 $gutter * ($toc_level + .5)
padding: ($gutter / 4) ($gutter * ($toc_level + 0.5))
padding-right: $gutter
a:hover span.toctree-expand
a:hover button.toctree-expand
@extend %toctree_hover_link_color
@if $toc_level > 2 and $toc_level < 5
li.toctree-l#{$toc_level}
@@ -146,7 +149,7 @@ html
background: darken($menu-vertical-background-color, 20%)
li.toctree-l3 > a
background: darken($menu-vertical-background-color, 20%)
span.toctree-expand
button.toctree-expand
color: darken($menu-vertical-background-color, 35%)
li.toctree-l3
&.current
@@ -154,7 +157,7 @@ html
background: darken($menu-vertical-background-color, 25%)
li.toctree-l4 > a
background: darken($menu-vertical-background-color, 25%)
span.toctree-expand
button.toctree-expand
color: darken($menu-vertical-background-color, 40%)
li.current ul
@@ -168,7 +171,7 @@ html
font-weight: normal
a
line-height: 18px
padding: $gutter / 4 $gutter
padding: ($gutter / 4) $gutter
display: block
position: relative
font-size: 90%
@@ -176,13 +179,13 @@ html
&:hover
background-color: lighten($menu-background-color, 10%)
cursor: pointer
span.toctree-expand
button.toctree-expand
color: $menu-link-light
&:active
background-color: $menu-logo-color
cursor: pointer
color: $menu-link-active
span.toctree-expand
button.toctree-expand
color: $menu-link-active
.wy-side-nav-search
@@ -201,7 +204,7 @@ html
border-color: darken($link-color, 5%)
img
display: block
margin: auto auto $gutter / 2 auto
margin: auto auto ($gutter / 2) auto
height: 45px
width: 45px
background-color: $menu-logo-color
@@ -212,11 +215,11 @@ html
font-size: 100%
font-weight: bold
display: inline-block
padding: $base-line-height / 6 $base-line-height / 4
padding: ($base-line-height / 6) ($base-line-height / 4)
margin-bottom: $gutter / 2
+font-smooth
&:hover
background: rgba(255,255,255,.1)
background: rgba(255, 255, 255, 0.1)
img.logo
display: block // display on its own line all the time
margin: 0 auto
@@ -224,15 +227,15 @@ html
width: auto
border-radius: 0
max-width: 100% // shrink on mobile, if appropriate
background: rgba(0,0,0,0) // make hover background of parent show up properly
background: rgba(0, 0, 0, 0) // make hover background of parent show up properly
&.icon
img.logo
margin-top: 0.85em // space it away from the title text
> div.version
margin-top: -1 * ($gutter / 4)
margin-top: -1 * $gutter / 4
margin-bottom: $gutter / 2
font-weight: normal
color: rgba(255,255,255,.3)
color: rgba(255, 255, 255, 0.3)
.wy-nav .wy-menu-vertical
header
@@ -244,7 +247,7 @@ html
color: $white
[data-menu-wrap]
+transition(all .2s ease-in)
+transition(all 0.2s ease-in)
position: absolute
opacity: 1
width: 100%
@@ -295,7 +298,7 @@ html
display: none
background: $link-color
color: $white
padding: $gutter / 4 $gutter / 2
padding: ($gutter / 4) ($gutter / 2)
position: relative
line-height: 50px
text-align: center
@@ -324,7 +327,7 @@ html
min-height: 100%
.wy-nav-content
padding: $gutter $gutter * 2
padding: $gutter ($gutter * 2)
height: 100%
max-width: $nav-content-width
margin: auto
@@ -333,7 +336,7 @@ html
position: fixed
width: 100%
height: 100%
background: rgba(0,0,0,.2)
background: rgba(0, 0, 0, 0.2)
display: none
z-index: $z-index-modal - 1
&.on
@@ -411,7 +414,7 @@ footer
@media screen and (min-width: $nav-media-query)
.wy-nav-content-wrap
background: rgba(0,0,0,.05)
background: rgba(0, 0, 0, 0.05)
.wy-nav-content
margin: 0
background: $section-background-color

61
src/sass/_theme_rst.sass
View File

@@ -56,7 +56,7 @@
pre.literal-block
white-space: pre
margin: 0
padding: $base-line-height / 2 $base-line-height / 2
padding: ($base-line-height / 2) ($base-line-height / 2)
font-family: $code-font-family
display: block
overflow: auto
@@ -75,21 +75,21 @@
.linenodiv pre
border-right: solid 1px lighten($table-border-color, 2%)
margin: 0
padding: $base-line-height / 2 $base-line-height / 2
padding: ($base-line-height / 2) ($base-line-height / 2)
font-family: $code-font-family
user-select: none
pointer-events: none
div[class^='highlight'] pre
white-space: pre
margin: 0
padding: $base-line-height / 2 $base-line-height / 2
padding: ($base-line-height / 2) ($base-line-height / 2)
display: block
overflow: auto
& .hll
// Line emphasis spans full width
display: block
margin: 0 -1 * $base-line-height / 2
padding: 0 $base-line-height / 2
margin: 0 (-1 * $base-line-height / 2)
padding: 0 ($base-line-height / 2)
pre.literal-block, div[class^='highlight'] pre, .linenodiv pre
font-family: $code-font-family
font-size: 12px
@@ -135,10 +135,10 @@
@extend .wy-alert.wy-alert-warning
// Some people put tables in notes. Let's give them very basic support.
.admonition table
border-color: rgba(0,0,0,.1)
border-color: rgba(0, 0, 0, 0.1)
td, th
background: transparent !important
border-color: rgba(0,0,0,.1) !important
border-color: rgba(0, 0, 0, 0.1) !important
.section ul, .toctree-wrapper ul
@extend .wy-plain-list-disc
.section ol.loweralpha, .section ol.loweralpha > li
@@ -200,14 +200,19 @@
// This is the #href that shows up on hover. Sphinx's is terrible so I hack it away.
h1, h2, h3, h4, h5, h6, dl dt, p.caption, table > caption, .code-block-caption
.headerlink
visibility: hidden
opacity: 0
font-size: 14px
font-family: FontAwesome
margin-left: 0.5em
@extend .fa
&:after
content: "\f0c1"
font-family: FontAwesome
&:hover .headerlink:after
visibility: visible
&:focus
opacity: 1
&:hover .headerlink
opacity: 1
// override the Wyrm accessibility anti-pattern of hiding button focus
.btn:focus
outline: 2px solid
table > caption .headerlink:after
font-size: 12px
@@ -234,14 +239,14 @@
font-family: $custom-font-family
font-weight: bold
background: $table-border-color
padding: $base-line-height / 4 $base-line-height / 2
padding: ($base-line-height / 4) ($base-line-height / 2)
margin: -$base-line-height
margin-bottom: $base-line-height
font-size: 100%
// Sphinx can highlight searched text with ?highlighted=searchterm
.highlighted
background: $highlight-color
box-shadow: 0 0 0 $base-line-height / 12 $highlight-color
box-shadow: 0 0 0 ($base-line-height / 12) $highlight-color
display: inline
font-weight: bold
@@ -289,14 +294,14 @@
> dt, > dd
margin-bottom: 0rem
dl.footnote
font-size: .9rem
font-size: 0.9rem
> dt
margin: 0rem .5rem .5rem 0rem
margin: 0rem 0.5rem 0.5rem 0rem
line-height: 1.2rem
word-break: break-all
font-weight: normal
> span.brackets
margin-right: .5rem
margin-right: 0.5rem
&:before
content: "["
&:after
@@ -304,13 +309,13 @@
> span.fn-backref
font-style: italic
> dd
margin: 0rem 0rem .5rem 0rem
margin: 0rem 0rem 0.5rem 0rem
line-height: 1.2rem
p
font-size: .9rem
font-size: 0.9rem
dl.option-list
kbd
font-size: .9rem
font-size: 0.9rem
// Both
html.writer-html4 & table.docutils.citation, table.docutils.footnote,
html.writer-html5 & dl.footnote
@@ -340,7 +345,7 @@
th > p, td > p
line-height: 1rem
margin-bottom: 0rem
font-size: .9rem
font-size: 0.9rem
&:not(.field-list)
@extend .wy-table-striped
// Remove bottom margin for the last element (and it's last child)
@@ -395,14 +400,14 @@
margin-bottom: $base-line-height / 2
// rST seems to want dds to be treated as the browser would, indented.
dd
margin: 0 0 $base-line-height / 2 $base-line-height
margin: 0 0 ($base-line-height / 2) $base-line-height
line-height: $base-line-height
html.writer-html4 & dl:not(.docutils),
html.writer-html5 & dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)
margin-bottom: $base-line-height
> dt
display: table
margin: $base-line-height / 4 0
margin: ($base-line-height / 4) 0
font-size: 90%
line-height: normal
background: lighten($class-color, 50%)
@@ -420,8 +425,8 @@
dl:not(.field-list) > dt
margin-bottom: $base-line-height / 4
border: none
border-left: solid 3px hsl(0,0%,80%)
background: hsl(0,0%,94%)
border-left: solid 3px hsl(0, 0%, 80%)
background: hsl(0, 0%, 94%)
color: $method-color
.headerlink
color: $headerlink-color
@@ -481,8 +486,8 @@
font-size: 80%
font-weight: 700
border-radius: $base-line-height / 6
padding: $base-line-height / 10 $base-line-height / 4
margin: auto $base-line-height / 12
padding: ($base-line-height / 10) ($base-line-height / 4)
margin: auto ($base-line-height / 12)
.versionmodified
font-style: italic

2
src/sass/_theme_variables.sass
View File

@@ -6,7 +6,7 @@ $fa-font-path: "~font-awesome/fonts"
$static-img: "../img/"
$nav-content-width: 800px
$nav-media-query: (($nav-desktop-width) + ($nav-content-width))
$nav-media-query: $nav-desktop-width + $nav-content-width
$mathjax-color: $text-color

40
src/theme.js
View File

@@ -112,7 +112,8 @@ function ThemeNav () {
// Add expand links to all parents of nested ul
$('.wy-menu-vertical ul').not('.simple').siblings('a').each(function () {
var link = $(this);
expand = $('<span class="toctree-expand"></span>');
expand =
$('<button class="toctree-expand" title="Open/close menu"></button>');
expand.on('click', function (ev) {
self.toggleCurrent(link);
ev.stopPropagation();
@@ -144,11 +145,19 @@ function ThemeNav () {
// If we found a matching link then reset current and re-apply
// otherwise retain the existing match
if (link.length > 0) {
$('.wy-menu-vertical .current').removeClass('current');
link.addClass('current');
link.closest('li.toctree-l1').parent().addClass('current');
$('.wy-menu-vertical .current')
.removeClass('current')
.attr('aria-expanded','false');
link.addClass('current')
.attr('aria-expanded','true');
link.closest('li.toctree-l1')
.parent()
.addClass('current')
.attr('aria-expanded','true');
for (let i = 1; i <= 10; i++) {
link.closest('li.toctree-l' + i).addClass('current');
link.closest('li.toctree-l' + i)
.addClass('current')
.attr('aria-expanded','true');
}
link[0].scrollIntoView();
}
@@ -187,13 +196,26 @@ function ThemeNav () {
nav.toggleCurrent = function (elem) {
var parent_li = elem.closest('li');
parent_li.siblings('li.current').removeClass('current');
parent_li.siblings().find('li.current').removeClass('current');
parent_li
.siblings('li.current')
.removeClass('current')
.attr('aria-expanded','false');
parent_li
.siblings()
.find('li.current')
.removeClass('current')
.attr('aria-expanded','false');
var children = parent_li.find('> ul li');
// Don't toggle terminal elements.
if (children.length) {
children.removeClass('current');
parent_li.toggleClass('current');
children
.removeClass('current')
.attr('aria-expanded','false');
parent_li
.toggleClass('current')
.attr('aria-expanded', function(i, old) {
return old == 'true' ? 'false' : 'true';
});
}
}