 }}){kind=logo}
-
+
{{ _('Navigation') }}
- Documentation » @@ -32,20 +40,22 @@
{{ _('Navigation') }}
{%- block content %}
-
{%- endblock %}
+
+{% macro prev_next() %}
+
+
@@ -59,3 +69,60 @@
{%- include "searchfield.html" %}
-
{%- block document %}
-
+ {%- if display_toc %}
+ {{ _('On this page') }}
- {{ toc }} -
+
+ {%- endif %}
{{ _('On this page') }}
+ {{ toc }} +
-
{{ _('Site navigation') }}
{{ toctree(includehidden=True, maxdepth=3, titles_only=True) }}
{% block body %}{% endblock %}
+ {{ prev_next() }}
{%- endblock %}
{{ _('Site navigation') }}
{% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %}
+ {% if prev -%}
+
+
+
+{% endmacro %}
+
+{% macro svgs() %}
+
+{% endmacro %}
diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css
index 3234a3726cd..ecc952d0e8e 100644
--- a/doc/_themes/sphinx13/static/sphinx13.css
+++ b/doc/_themes/sphinx13/static/sphinx13.css
@@ -6,38 +6,89 @@
--colour-sphinx-blue: #0A507A;
--colour-text: #333;
--colour-links-light: #057;
+ --admonition-radius: 3px;
+
+ /* colours for admonition titles */
+ --color-admonition-bg: hsl(0, 0%, 90%);
+ --color-admonition-fg: hsl(0, 0%, 50%);
+ --colour-warning-bg: hsl(28.5, 74%, 90%);
+ --colour-warning-fg: hsl(28.5, 74%, 50%);
+ --colour-note-bg: hsl(219.5, 84%, 90%);
+ --colour-note-fg: hsl(219.5, 84%, 50%);
+ --colour-success-bg: hsl(150, 36.7%, 90%);
+ --colour-success-fg: hsl(150, 36.7%, 50%);
+ --colour-error-bg: hsl(0, 37%, 90%);
+ --colour-error-fg: hsl(0, 37%, 50%);
+ --colour-todo-bg: hsl(266.8, 100%, 90%);
+ --colour-todo-fg: hsl(266.8, 100%, 50%);
+
+ /* icons used for admonition titles */
+ --icon-pencil: url('data:image/svg+xml;charset=utf-8,');
+ --icon-abstract: url('data:image/svg+xml;charset=utf-8,');
+ --icon-info: url('data:image/svg+xml;charset=utf-8,');
+ --icon-flame: url('data:image/svg+xml;charset=utf-8,');
+ --icon-question: url('data:image/svg+xml;charset=utf-8,');
+ --icon-warning: url('data:image/svg+xml;charset=utf-8,');
+ --icon-failure: url('data:image/svg+xml;charset=utf-8,');
+ --icon-spark: url('data:image/svg+xml;charset=utf-8,');
}
body {
font-family: var(--fonts-sans-serif);
margin: 0 auto;
- color: var(--colour-text);
+ color: var(var(--colour-text));
}
.pageheader {
+ position: sticky;
+ top: 0;
+ z-index: 99;
+ height: 3rem;
display: flex;
column-gap: 1em;
align-items: center;
+ justify-content: space-between;
width: 100%;
background-color: var(--colour-sphinx-blue);
padding: 10px 20px;
+ box-sizing: border-box;
+}
+
+.pageheader .brand {
+ display: flex;
+ align-items: baseline;
+ column-gap: 1em;
+ color: white;
+ text-decoration: none;
}
-.pageheader a {
- width: 5%;
+.pageheader .brand a {
+ width: 2em;
}
-.pageheader img {
+.pageheader .brand img {
filter: invert(1) drop-shadow(1px 1px 2px black);
}
-.pageheader h1{
+.pageheader .brand h1 {
color: white;
margin: 0;
- font-weight: 600;
- font-size: 3.5rem;
+ font-weight: 400;
+ font-size: 2em;
line-height: 1;
- font-variant: small-caps;
+}
+
+.pageheader .icons a {
+ color: white;
+}
+
+.pageheader .icons a:hover {
+ color: rgba(255, 255, 255, 0.8);
+}
+
+.pageheader .icons svg {
+ height: 1.6em;
+ width: 1.6em;
}
div.document {
@@ -54,6 +105,9 @@ div.body {
}
div.related {
+ position: sticky;
+ top: 3rem;
+ z-index: 99;
display: flex;
color: white;
background-color: var(--colour-sphinx-blue);
@@ -81,20 +135,31 @@ div.sphinxsidebarwrapper {
div.sphinxsidebar {
position: sticky;
- top: 0;
+ top: 4.6rem;
align-self: flex-start;
- height: 100vh;
+ height: calc(100vh - 4.6rem);
width: 250px;
+ min-width: 150px;
overflow-y: auto;
overflow-wrap: break-word;
margin: 0;
- padding-right: 15px;
- padding-top: 0.5em;
+ padding: 0.5em 15px 0.5em 10px;
font-size: 1em;
}
+/* horizontal line between sidebar components */
+div.sphinxsidebar div:not(:first-child) {
+ border-top: 1px solid var(--colour-sphinx-blue);
+}
+
+/* overwrite color from basic theme */
+div.sphinxsidebar input {
+ border: 1px solid var(--colour-sphinx-blue);
+}
+
div.sphinxsidebar h3 {
- font-size: 1.5em;
+ font-size: 1.2em;
+ font-weight: 300;
margin-top: 0;
margin-bottom: 0.5em;
padding-top: 0.5em;
@@ -169,6 +234,11 @@ div.footer a {
/* -- body styles ----------------------------------------------------------- */
+.body :target {
+ /* ensure targets are not obscured by top-bar when they are navigated to */
+ scroll-margin-top: 6.5rem;
+}
+
p {
margin: 0.8em 0 0.5em 0;
}
@@ -186,7 +256,7 @@ h1 {
margin: 10px 0 0 0;
font-size: 2.4em;
color: var(--colour-sphinx-blue);
- font-weight: 300;
+ font-weight: 400;
}
h1 span.pre {
@@ -198,7 +268,7 @@ h1 span.pre {
h2 {
margin: 1em 0 0.2em 0;
font-size: 1.5em;
- font-weight: 300;
+ font-weight: 400;
padding: 0;
color: #174967;
}
@@ -206,7 +276,7 @@ h2 {
h3 {
margin: 1em 0 -0.3em 0;
font-size: 1.3em;
- font-weight: 300;
+ font-weight: 400;
}
div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a {
@@ -311,6 +381,10 @@ aside.topic {
background-color: #f8f8f8;
}
+p.topic-title {
+ margin-top: 0;
+}
+
table {
border-collapse: collapse;
margin: 0 -0.5em 0 -0.5em;
@@ -324,7 +398,7 @@ div.admonition, div.warning {
font-size: 0.9em;
margin: 1em 0 1em 0;
border: 1px solid #86989B;
- border-radius: 2px;
+ border-radius: var(--admonition-radius);
background-color: #f7f7f7;
padding: 1rem;
}
@@ -338,9 +412,109 @@ div.admonition > pre, div.warning > pre {
margin: 0.4em 1em 0.4em 1em;
}
-div.admonition > p.admonition-title,
+div.admonition > p.admonition-title {
+ position: relative;
+ font-weight: 500;
+ background-color: var(--color-admonition-bg);
+ margin: -1rem -1rem 0.8rem -1rem;
+ padding: 0.3rem 1rem 0.3rem 2rem;
+ border-radius: var(--admonition-radius) var(--admonition-radius) 0 0;
+}
+
+div.attention > p.admonition-title,
+div.danger > p.admonition-title,
+div.error > p.admonition-title {
+ background-color: var(--colour-error-bg);
+}
+
+div.important > p.admonition-title,
+div.caution > p.admonition-title,
div.warning > p.admonition-title {
- font-weight: bold;
+ background-color: var(--colour-warning-bg);
+}
+
+div.note > p.admonition-title {
+ background-color: var(--colour-note-bg);
+}
+
+div.hint > p.admonition-title,
+div.tip > p.admonition-title,
+div.seealso > p.admonition-title {
+ background-color: var(--colour-success-bg);
+}
+
+div.admonition-todo > p.admonition-title {
+ background-color: var(--colour-todo-bg);
+}
+
+p.admonition-title::before {
+ content: "";
+ height: 1rem;
+ left: .5rem;
+ position: absolute;
+ width: 1rem;
+ background-color: #5f5f5f;
+}
+
+div.admonition > p.admonition-title::before {
+ background-color: var(--color-admonition-fg);
+ -webkit-mask-image: var(--icon-abstract);
+ mask-image: var(--icon-abstract);
+}
+div.attention > p.admonition-title::before {
+ background-color: var(--colour-error-fg);
+ -webkit-mask-image: var(--icon-warning);
+ mask-image: var(--icon-warning);
+}
+div.caution > p.admonition-title::before {
+ background-color: var(--colour-warning-fg);
+ -webkit-mask-image: var(--icon-spark);
+ mask-image: var(--icon-spark);
+}
+div.danger > p.admonition-title::before {
+ background-color: var(--colour-error-fg);
+ -webkit-mask-image: var(--icon-spark);
+ mask-image: var(--icon-spark);
+}
+div.error > p.admonition-title::before {
+ background-color: var(--colour-error-fg);
+ -webkit-mask-image: var(--icon-failure);
+ mask-image: var(--icon-failure);
+}
+div.hint > p.admonition-title::before {
+ background-color: var(--colour-success-fg);
+ -webkit-mask-image: var(--icon-question);
+ mask-image: var(--icon-question);
+}
+div.important > p.admonition-title::before {
+ background-color: var(--colour-warning-fg);
+ -webkit-mask-image: var(--icon-flame);
+ mask-image: var(--icon-flame);
+}
+div.note > p.admonition-title::before {
+ background-color: var(--colour-note-fg);
+ -webkit-mask-image: var(--icon-pencil);
+ mask-image: var(--icon-pencil);
+}
+div.seealso > p.admonition-title::before {
+ background-color: var(--colour-success-fg);
+ -webkit-mask-image: var(--icon-info);
+ mask-image: var(--icon-info);
+}
+div.tip > p.admonition-title::before {
+ background-color: var(--colour-success-fg);
+ -webkit-mask-image: var(--icon-info);
+ mask-image: var(--icon-info);
+}
+div.admonition-todo > p.admonition-title::before {
+ background-color: var(--colour-todo-fg);
+ -webkit-mask-image: var(--icon-pencil);
+ mask-image: var(--icon-pencil);
+}
+div.warning > p.admonition-title::before {
+ background-color: var(--colour-warning-fg);
+ -webkit-mask-image: var(--icon-warning);
+ mask-image: var(--icon-warning);
}
div.warning {
@@ -373,11 +547,132 @@ div.viewcode-block:target {
/* media queries */
/* Reduce padding & margins for smaller screens */
-@media (max-width: 750px) {
+@media (max-width: 768px) {
.sphinxsidebar {
display: none;
}
div.body {
border-left: none;
+ padding-left: 0.5em;
+ padding-right: 0.5em;
}
}
+
+/* Next/previous content footer */
+.related-pages {
+ display: flex;
+ flex-direction: row;
+ justify-content: space-between;
+ margin-top: 2rem;
+ font-size: smaller;
+}
+.related-pages .next-page {
+ text-align: right;
+}
+.related-pages a.prev-page,
+.related-pages a.next-page {
+ flex: 1 1 0%;
+ display: flex;
+ align-items: center;
+ border-radius: .25rem;
+ padding: .25rem;
+ text-decoration: none;
+}
+.related-pages a.prev-page {
+ justify-content: flex-start;
+ padding-left: 0;
+}
+.related-pages a.next-page {
+ justify-content: flex-end;
+ padding-right: 0;
+}
+.related-pages a:hover {
+ background-color: #f8f8f8;
+}
+.related-pages a .context {
+ font-size: small;
+ color: #5f5f5f;
+}
+.related-pages svg {
+ height: .75rem;
+ width: .75rem;
+ margin: 0 .5rem;
+ flex-shrink: 0;
+}
+.related-pages .prev-page svg {
+ transform: rotate(180deg);
+}
+
+/* ReadtheDocs docs selector */
+/* see https://docs.readthedocs.io/en/stable/flyout-menu.html */
+.rst-versions.rst-badge {
+ background-color: #f7f7f7;
+ border: 1px solid var(--colour-sphinx-blue);
+ border-radius: var(--admonition-radius);
+ color: var(--colour-sphinx-blue);
+}
+.rst-versions .rst-current-version {
+ background-color: #f7f7f7;
+ border-radius: var(--admonition-radius);
+ color: var(--colour-sphinx-blue);
+}
+.rst-versions .rst-current-version .fa {
+ color: var(--colour-sphinx-blue);
+}
+.rst-versions .rst-other-versions {
+ border-radius: 0 0 var(--admonition-radius) var(--admonition-radius);
+ border-top: 1px solid var(--colour-sphinx-blue);
+ background-color: #f7f7f7;
+ color: var(--colour-text);
+}
+.rst-versions .rst-other-versions dd a {
+ color: var(--colour-sphinx-blue);
+}
+
+
+/* Landing page */
+.sphinx-tagline * {
+ hyphens: none !important;
+ font-style: italic !important;
+}
+/* By default align the sphinx-features one per-row and center them,
+then for larger screens align them two per-row. */
+.sphinx-features {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 10px;
+ justify-content: center;
+}
+.sphinx-feature {
+ flex: 1 1 100%;
+ margin: 0 !important;
+ background-color: white !important;
+}
+.sphinx-feature p {
+ hyphens: none !important;
+}
+div.sphinx-feature > p.admonition-title {
+ background-color: #f7f7f7 !important;
+ padding-left: 1rem;
+ font-weight: bold;
+}
+div.sphinx-feature > p.admonition-title::before {
+ display: none;
+}
+@media (min-width: 768px) {
+ .sphinx-feature {
+ flex: 0 0 auto;
+ box-sizing: border-box;
+ width: 48%;
+ }
+}
+.sphinx-users {
+ text-align: center;
+ font-weight: 500;
+}
+.sphinx-users-logos {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: center;
+ gap: 10px;
+}
diff --git a/doc/conf.py b/doc/conf.py
index 49fcba462b1..893d4862666 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,10 +1,11 @@
# Sphinx documentation build configuration file
+from __future__ import annotations
import os
import re
import time
-import sphinx
+from sphinx import __display_version__
os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
@@ -18,6 +19,7 @@
'sphinx.ext.viewcode',
'sphinx.ext.inheritance_diagram',
'sphinx.ext.coverage',
+ 'sphinx.ext.graphviz',
]
coverage_statistics_to_report = coverage_statistics_to_stdout = True
templates_path = ['_templates']
@@ -25,8 +27,7 @@
project = 'Sphinx'
copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
-version = sphinx.__display_version__
-release = version
+release = version = __display_version__
show_authors = True
nitpicky = True
show_warning_types = True
@@ -114,15 +115,15 @@
autodoc_member_order = 'groupwise'
autosummary_generate = False
-todo_include_todos = True
+todo_include_todos = 'READTHEDOCS' not in os.environ
extlinks = {
- 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/' '%s.html', '%s'),
+ 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/%s.html', '%s'),
'duref': (
- 'https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s',
+ 'https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#%s',
'%s',
),
- 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/' 'roles.html#%s', '%s'),
- 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/' 'directives.html#%s', '%s'),
+ 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/roles.html#%s', '%s'),
+ 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/directives.html#%s', '%s'),
}
man_pages = [
@@ -137,7 +138,7 @@
(
'man/sphinx-quickstart',
'sphinx-quickstart',
- 'Sphinx documentation ' 'template generator',
+ 'Sphinx documentation template generator',
'',
1,
),
@@ -154,7 +155,7 @@
'Sphinx',
'The Sphinx documentation builder.',
'Documentation tools',
- 1,
+ True,
),
]
@@ -183,7 +184,10 @@
('py:class', 'Node'), # sphinx.domains.Domain
('py:class', 'NullTranslations'), # gettext.NullTranslations
('py:class', 'RoleFunction'), # sphinx.domains.Domain
+ ('py:class', 'RSTState'), # sphinx.utils.parsing.nested_parse_to_nodes
('py:class', 'Theme'), # sphinx.application.TemplateBridge
+ ('py:class', 'StringList'), # sphinx.utils.parsing.nested_parse_to_nodes
+ ('py:class', 'system_message'), # sphinx.utils.docutils.SphinxDirective
('py:class', 'TitleGetter'), # sphinx.domains.Domain
('py:class', 'XRefRole'), # sphinx.domains.Domain
('py:class', 'docutils.nodes.Element'),
@@ -234,13 +238,14 @@
# -- Extension interface -------------------------------------------------------
from sphinx import addnodes # NoQA: E402
+from sphinx.application import Sphinx # NoQA: E402, TCH001
-event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
+_event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
def parse_event(env, sig, signode):
- m = event_sig_re.match(sig)
- if not m:
+ m = _event_sig_re.match(sig)
+ if m is None:
signode += addnodes.desc_name(sig, sig)
return sig
name, args = m.groups()
@@ -274,19 +279,59 @@ def linkify(match):
source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog)
-def setup(app):
+REDIRECT_TEMPLATE = """
+
+
+
+
+
+
+
+
+
+ {%- else %}
+
+ {%- endif %}
+ {% if next -%}
+
+
+ {{ _("Previous") }}
+
+ {% if prev.link == pathto(root_doc) %}
+ {{ _("Home") }}
+ {% else %}
+ {{ prev.title }}
+ {% endif %}
+
+
+
+
+ {%- endif %}
+
+ {{ _("Next") }}
+
+ {{ next.title }}
+ You should have been redirected.
+ If not, click here to continue. + + +""" # noqa: E501 + + +def build_redirects(app: Sphinx, exception: Exception | None) -> None: + # this is a very simple implementation of + # https://github.com/wpilibsuite/sphinxext-rediraffe/blob/main/sphinxext/rediraffe.py + # to re-direct some old pages to new ones + if exception is not None or app.builder.name != 'html': + return + for page, rel_redirect in ( + (('development', 'overview.html'), 'index.html'), + (('development', 'builders.html'), 'howtos/builders.html'), + (('development', 'theming.html'), 'html_themes/index.html'), + (('development', 'templating.html'), 'html_themes/templating.html'), + (('development', 'tutorials', 'helloworld.html'), 'extending_syntax.html'), + (('development', 'tutorials', 'todo.html'), 'extending_build.html'), + (('development', 'tutorials', 'recipe.html'), 'adding_domain.html'), + ): + path = app.outdir.joinpath(*page) + if path.exists(): + continue + path.parent.mkdir(parents=True, exist_ok=True) + with path.open('w', encoding='utf-8') as f: + f.write(REDIRECT_TEMPLATE.replace('{{rel_url}}', rel_redirect)) + + +def setup(app: Sphinx) -> None: from sphinx.ext.autodoc import cut_lines from sphinx.util.docfields import GroupedField app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) app.connect('source-read', linkify_issues_in_changelog) - app.add_object_type( - 'confval', - 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value', - ) + app.connect('build-finished', build_redirects) fdesc = GroupedField('parameter', label='Parameters', names=['param'], can_collapse=True) app.add_object_type( - 'event', 'event', 'pair: %s; event', parse_event, doc_field_types=[fdesc] + 'event', + 'event', + 'pair: %s; event', + parse_event, + doc_field_types=[fdesc], ) diff --git a/doc/development/builders.rst b/doc/development/howtos/builders.rst similarity index 100% rename from doc/development/builders.rst rename to doc/development/howtos/builders.rst diff --git a/doc/development/howtos/index.rst b/doc/development/howtos/index.rst new file mode 100644 index 00000000000..9800655d18c --- /dev/null +++ b/doc/development/howtos/index.rst @@ -0,0 +1,8 @@ +How-tos +======= + +.. toctree:: + :maxdepth: 1 + + setup_extension + builders diff --git a/doc/development/overview.rst b/doc/development/howtos/setup_extension.rst similarity index 66% rename from doc/development/overview.rst rename to doc/development/howtos/setup_extension.rst index df8f5bb8b73..bcb4dafae4a 100644 --- a/doc/development/overview.rst +++ b/doc/development/howtos/setup_extension.rst @@ -1,10 +1,5 @@ -Developing extensions overview -============================== - -This page contains general information about developing Sphinx extensions. - -Make an extension depend on another extension ---------------------------------------------- +Depend on another extension +=========================== Sometimes your extension depends on the functionality of another Sphinx extension. Most Sphinx extensions are activated in a @@ -19,12 +14,12 @@ use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will activate another extension at run-time, ensuring that you have access to its functionality. -For example, the following code activates the ``recommonmark`` extension: +For example, the following code activates the :mod:`sphinx.ext.autodoc` extension: .. code-block:: python def setup(app): - app.setup_extension("recommonmark") + app.setup_extension('sphinx.ext.autodoc') .. note:: diff --git a/doc/development/theming.rst b/doc/development/html_themes/index.rst similarity index 99% rename from doc/development/theming.rst rename to doc/development/html_themes/index.rst index 7853e4d74b5..31d6cfdfdbb 100644 --- a/doc/development/theming.rst +++ b/doc/development/html_themes/index.rst @@ -1,3 +1,5 @@ +.. _extension-html-theme: + HTML theme development ====================== @@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call Templating ---------- +.. toctree:: + :hidden: + + templating + The :doc:`guide to templating