diff --git a/doc/python_api/requirements.txt b/doc/python_api/requirements.txt index 14d60036cb4..1c3b92f7498 100644 --- a/doc/python_api/requirements.txt +++ b/doc/python_api/requirements.txt @@ -9,4 +9,4 @@ requests==2.31.0 # Only needed to match the theme used for the official documentation. # Without this theme, the default theme will be used. -sphinx_rtd_theme==1.3.0rc1 +furo==2024.1.29 diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 0a7702bf09c..02df13af1b9 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -1929,22 +1929,30 @@ def write_sphinx_conf_py(basepath): # The theme 'sphinx_rtd_theme' is no longer distributed with sphinx by default, only use when available. fw(r""" try: - __import__('sphinx_rtd_theme') - html_theme = 'sphinx_rtd_theme' + import furo + html_theme = "furo" + del furo except ModuleNotFoundError: pass -""") +if html_theme == "furo": + html_theme_options = { + "light_css_variables": { + "color-brand-primary": "#265787", + "color-brand-content": "#265787", + }, + } - fw("if html_theme == 'sphinx_rtd_theme':\n") - fw(" html_theme_options = {\n") - fw(" 'display_version': False,\n") - # fw(" 'analytics_id': '',\n") - # fw(" 'collapse_navigation': True,\n") - fw(" 'sticky_navigation': False,\n") - fw(" 'navigation_depth': 1,\n") - fw(" 'includehidden': False,\n") - # fw(" 'titles_only': False\n") - fw(" }\n\n") + html_sidebars = { + "**": [ + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/scroll-start.html", + "sidebar/navigation.html", + "sidebar/scroll-end.html", + # "sidebar/variant-selector.html", + ] + } +""") # not helpful since the source is generated, adds to upload size. fw("html_copy_source = False\n") @@ -1961,7 +1969,7 @@ except ModuleNotFoundError: fw("html_logo = 'static/blender_logo.svg'\n") # Disable default `last_updated` value, since this is the date of doc generation, not the one of the source commit. fw("html_last_updated_fmt = None\n\n") - fw("if html_theme == 'sphinx_rtd_theme':\n") + fw("if html_theme == 'furo':\n") fw(" html_css_files = ['css/version_switch.css']\n") fw(" html_js_files = ['js/version_switch.js']\n") diff --git a/doc/python_api/static/css/theme_overrides.css b/doc/python_api/static/css/theme_overrides.css index 5ab449044db..c92ea04aacc 100644 --- a/doc/python_api/static/css/theme_overrides.css +++ b/doc/python_api/static/css/theme_overrides.css @@ -1,19 +1,323 @@ -/* Hide home icon in search area */ -.wy-side-nav-search > a:hover {background: none; opacity: 0.9} -.wy-side-nav-search > a.icon::before {content: none} +/* + * This stylesheet is applied after the theme's default one, + * and thus any overrides or additions can be added here. + * + * More info: + * https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file + */ -.wy-nav-content { - max-width: 1000px !important; +body { + --sidebar-caption-font-size: var(--font-size--normal); + --toc-title-font-size: var(--font-size--normal); + --toc-font-size: var(--sidebar-item-font-size); + --admonition-font-size: var(--font-size--normal); + --admonition-title-font-size: var(--font-size--normal); + --color-api-name: #e87d0d; } -/* Fix long titles on mobile */ -h1, h2, h3, h4, h5, h6 {word-break: break-all} +h1, +h2, +h3 { + margin-top: 1.75rem; + margin-bottom: 1rem; +} -/* Temp fix for https://github.com/readthedocs/sphinx_rtd_theme/pull/1109 */ -.hlist tr { - display: -ms-flexbox; - display: flex; - flex-flow: row wrap; - } +h1 { + font-size: 2em; +} -.hlist td {margin-right: auto} +h2 { + font-size: 1.5em; +} + +h3 { + font-size: 1.25em; +} + +h4, +h5, +h6, +.rubric { + margin-top: 1.25rem; + margin-bottom: 0.75rem; + font-size: 1.125em; +} + +/* Reduce the margins on top/bottom of horizontal lines. */ +hr.docutils { + margin: 1rem 0; +} + + +/* Slightly decrease text to make the text fit on one line */ +.sidebar-brand-text { + font-size: 1.4rem; +} + +.toctree-checkbox~label .icon svg { + transition: transform 0.25s ease-out; +} + +/* Add more visual weight to definition terms */ +dl dt { + font-weight: bold !important +} + +/* Fixes to field list, see #104636 */ +dl.field-list { + display: grid; + grid-template-columns: auto minmax(80%, 95%); + + p { + margin-bottom: 0; + } +} + +/* TABLE & FIGURE */ + +/* Cell's vertical align. */ +/* use "valign" class for middle align */ +table.docutils:not(.valign) td { + vertical-align: baseline; +} + +/* Decrease whitespace above figure and add it below */ +figure { + padding-bottom: 0.5rem; +} + +figcaption { + margin-bottom: 0.5rem !important; + + p { + margin-top: 0; + } +} + +/* End TABLE & FIGURE. */ + +/* Force admonition to span the full width if close to a figure */ +.admonition { + clear: both; +} + +/* Use secondary font color for caption text */ +figcaption, +caption { + color: var(--color-foreground-secondary); + font-size: var(--font-size--small) +} + +/* A bit hacky, revert the themes styling of kbd */ +kbd:not(.compound) { + all: revert; +} + +/* Only style parent kbd elements instead of the individual children */ +:not(dl.option-list)> :not(kbd):not(kbd)>kbd, +.menuselection { + background-color: var(--color-background-secondary); + border: 1px solid var(--color-foreground-border); + border-radius: .2rem; + box-shadow: 0 .0625rem 0 rgba(0, 0, 0, .2), inset 0 0 0 .125rem var(--color-background-secondary); + color: var(--color-foreground-primary); + display: inline-block; + margin: 0; + padding: 0 .2rem; +} + +.highlight .nc, +.highlight .nn, +.highlight .gu { + text-decoration-line: none !important; +} + +.caption .menuselection { + background-color: transparent; + border: none; +} + +a { + text-decoration: none; +} + +/* Quotes for Fig. "link". */ +a[href^="#fig-"]::before { + content: "\201c"; +} + +a[href^="#fig-"]::after { + content: "\201d"; +} + +/* Mark external links. */ +a.external { + filter: brightness(150%); +} + +/* List blender.org as internal. */ +.external[href^="https://www.blender.org"], +.external[href^="https://docs.blender.org"], +.external[href^="https://projects.blender.org"], +.external[href^="https://builder.blender.org"], +.external[href^="https://code.blender.org"], +.external[href^="https://translate.blender.org"], +.external[href^="https://fund.blender.org"], +.external[href^="blender_manual_html.zip"], +.external[href^="blender_manual_epub.zip"], +.external[href^="https://archive.blender.org"] { + filter: revert; +} + +/* ".. container::" lead, block text float around image. */ +.lead { + clear: both; + width: 100%; +} + +/* Start reference admonition. */ +.admonition.refbox { + border-color: rgb(50, 50, 50); +} + +.admonition.refbox>.admonition-title { + background-color: rgba(50, 50, 50, 0.2); + border-color: rgb(50, 50, 50); +} + +.admonition.refbox>.admonition-title::before { + background-color: var(--color-content-foreground); +} + +/* 'refbox' field. */ +.refbox .field-list .field-name, +.refbox .field-list .field-body { + padding: 0px; +} + +.refbox dl dt { + font-weight: normal +} + +/* End reference admonition. */ + +/* Applied on main index:sections. */ + +.global-index-toc { + display: none; +} + +/* Start section cards. */ +.toc-cards { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(350px, 1fr)); + grid-gap: 20px; + list-style-type: none; + margin-bottom: 24px; +} + +.card { + border-radius: .3em; + user-select: none; +} + +.card div.figure, +.card figure { + margin-bottom: 0px; + display: block; +} + +.card img { + border-top-left-radius: .3em; + border-top-right-radius: .3em; +} + +.card dl { + margin-bottom: 10px +} + +.card dl dt>a { + display: block; + width: 100%; + margin-bottom: 10px; +} + +.card dl dt a em, +.card dl dt a span { + font-weight: bold; + font-style: normal; + font-size: 1.3em; +} + +.card dl dt { + padding: 0px 15px 0px !important +} + +.card dl dd { + padding: 0px 15px 5px 15px; + font-style: normal; + margin: 0px; + color: var(--color-foreground-secondary); + font-size: 90%; +} + +.card { + box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1); +} + +#getting-started .card { + box-shadow: none; +} + +/* End section cards. */ + +/* Start custom toctree. */ +/* Indent all lines following the first. */ +.toctree-wrapper * a { + display: block; + padding-top: 0.25em; +} + +.toctree-wrapper ul { + list-style: none; + padding-left: 0; +} + +/* Underline provided by nested ul (not li). */ +.toctree-wrapper * ul { + margin-bottom: 1rem !important; + border-top: solid var(--color-background-border) 1px; + padding-left: 2em; +} + +/* End custom toctree. */ + +/* Start footer contribute link */ +.footer-contribute { + display: block; + font-size: var(--font-size--small); +} + +.bottom-of-page { + padding-bottom: 0; +} + +.footer-contribute ul { + margin: 0; + padding: 0; + padding-bottom: 1rem +} + +.footer-contribute li { + display: inline; + list-style-type: none; + padding-right: 1.5rem; +} + +@media print { + .footer-contribute { + display: none; + } +} + +/* End footer contribute link */ \ No newline at end of file diff --git a/doc/python_api/static/css/version_switch.css b/doc/python_api/static/css/version_switch.css index adb80b01c0a..80d5c2a52b0 100644 --- a/doc/python_api/static/css/version_switch.css +++ b/doc/python_api/static/css/version_switch.css @@ -1,46 +1,35 @@ -/* Override RTD theme */ -.rst-versions { - display: none; - border-top: 0px; - overflow: visible; -} -.version-btn.vdeact { - cursor: default; - color: dimgray; -} - -.version-btn.vdeact::after { - content: ""; -} #versionwrap { + margin: 0; display: flex; padding-top: 2px; - font-size: 90%; + padding-left: 0; + font-size: var(--sidebar-item-font-size); justify-content: center; flex-wrap: wrap; } + +#versionwrap>ul { + list-style: none; +} + +#versionwrap>li { + display: flex; + width: 50%; +} + .version-btn { display: inline-block; - background-color: #272525; - width: 140px; + background-color: var(--color-sidebar-background); + width: 100%; text-align: center; padding: 3px 10px; margin: 0px 5px 4px; vertical-align: middle; - color: #27AE60; - border: solid 1px #444444; + color: var(--color-link); + border: solid 1px var(--color-sidebar-background-border); border-radius: 3px; cursor: pointer; z-index: 400; - transition: border-color 0.4s; -} -.version-btn::after { - content:"\f0d8"; - display: inline; - font: normal normal normal 16px/1 FontAwesome; - color: #8d8c8c; - vertical-align: top; - padding-left: 0.5em; } .version-btn-open::after { color: gray; @@ -50,7 +39,7 @@ } .version-btn-open { color: gray; - border: solid 1px gray; + border: solid 1px var(--color-sidebar-background-border); } .version-btn.wait { cursor: wait; @@ -63,30 +52,32 @@ display: none; position: absolute; bottom: 28px; - width: 140px; + width: 50%; margin: 0 5px; padding-bottom: 4px; - background-color: #0003; border-radius: 3px; box-shadow: 0 0 6px #000C; z-index: 999; max-height: calc(100vh - 30px); + overflow-x: clip; overflow-y: auto; cursor: default; } .version-title { padding: 5px; - color: black; + color: var(--color-content-foreground); text-align: center; font-size: 102%; - background-color: #27ae60; - border-bottom: solid 1.5px #444; + font-weight: 700; + background-color: var(--color-brand-primary); + border-bottom: solid 1.5px var(--color-sidebar-background-border); } .version-list { + padding-left: 0; + margin-top: 0; margin-bottom: 4px; text-align: center; - background-color: #000C; - border: solid 1px gray; + border: solid 1px var(--color-sidebar-background-border); border-radius: 0px 0px 3px 3px; } .version-list a, .version-list span, .version-list li { @@ -97,32 +88,20 @@ width: 100%; margin: 0; padding: 4px 0px; - color: #404040; + color: var(--color-sidebar-link-text); } .version-list li { - background-color: #ede9e9; - color: #404040; + background-color: var(--color-sidebar-background); + color: var(--color-sidebar-link-text); padding: 1px; } -.version-list li:hover, .version-list li a:focus { - background-color: #b9cfda; + +.version-list li:hover, +.version-list li a:focus { + background-color: var(--color-background-hover); } -.version-list li.selected, .version-list li.selected:hover { - background-color: #8d8c8c; -} -.version-list li.selected span { - cursor: default; - outline-color: red; -} -.version-arrow { - position: absolute; - width: 8px; - height: 8px; - left: 50%; - bottom: 4px; - margin-left: -4px; - transform: rotate(225deg); - background: #ede9e9; - border: 1px solid gray; - border-width: 1px 0 0 1px; + +.version-list li.selected { + background: var(--color-sidebar-item-background--current); + font-weight: 700; } diff --git a/doc/python_api/templates/base.html b/doc/python_api/templates/base.html new file mode 100644 index 00000000000..5fb72406236 --- /dev/null +++ b/doc/python_api/templates/base.html @@ -0,0 +1,6 @@ +{%- extends "!base.html" -%} + +{%- block theme_scripts -%} +{{ super() }} + +{%- endblock -%} diff --git a/doc/python_api/templates/footer.html b/doc/python_api/templates/components/footer_contribute.html similarity index 77% rename from doc/python_api/templates/footer.html rename to doc/python_api/templates/components/footer_contribute.html index 394aad996cf..3a34cf9ed0a 100644 --- a/doc/python_api/templates/footer.html +++ b/doc/python_api/templates/components/footer_contribute.html @@ -1,6 +1,3 @@ -{# For the "Report Issue" button on the bottom of pages. #} -{%- extends "!footer.html" %} -{%- block extrafooter %} {%- if not pagename in ("search", "404", "genindex") and hasdoc(pagename) %} -{%- endif %} -{% endblock %} +{%- endif %} \ No newline at end of file diff --git a/doc/python_api/templates/page.html b/doc/python_api/templates/page.html new file mode 100644 index 00000000000..f220bfeee4b --- /dev/null +++ b/doc/python_api/templates/page.html @@ -0,0 +1,6 @@ +{%- extends "!page.html" -%} + +{%- block footer -%} +{{ super() }} +{%- include "components/footer_contribute.html" -%} +{%- endblock footer -%} \ No newline at end of file diff --git a/doc/python_api/templates/versions.html b/doc/python_api/templates/sidebar/variant-selector.html similarity index 71% rename from doc/python_api/templates/versions.html rename to doc/python_api/templates/sidebar/variant-selector.html index 482d4361207..4eb56915f18 100644 --- a/doc/python_api/templates/versions.html +++ b/doc/python_api/templates/sidebar/variant-selector.html @@ -7,7 +7,6 @@ {{ release }} +