From 3f1ed829e025e31a2b4918b4fdf8e190d4f8bfe1 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 16 Feb 2023 02:30:58 -0800 Subject: [PATCH 01/22] [pre-commit.ci] pre-commit autoupdate (#676) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .pre-commit-config.yaml | 2 +- tests/test_build.py | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0590e95b..9192d071 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -28,7 +28,7 @@ repos: - id: flake8 - repo: https://github.com/psf/black - rev: 22.12.0 + rev: 23.1.0 hooks: - id: black diff --git a/tests/test_build.py b/tests/test_build.py index 35c26dfc..d0279687 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -141,7 +141,6 @@ def test_build_book(sphinx_build_factory, file_regression): def test_navbar_options_home_page_in_toc(sphinx_build_factory): - sphinx_build = sphinx_build_factory( "base", confoverrides={"html_theme_options.home_page_in_toc": True} ).build( From 1656b772f78153e18bebde637c27482e30d4365c Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 16 Feb 2023 11:51:04 +0100 Subject: [PATCH 02/22] UPGRADE/BREAKING: PyData v0.13 and HTML refactoring (#677) --- .github/workflows/lighthouserc.json | 6 +- CONTRIBUTING.md | 2 +- docs/_static/logo-square.png | Bin 0 -> 2620 bytes docs/_static/logo-wide-dark.svg | 13 ++ docs/_templates/sections/header.html | 2 - docs/_templates/test.html | 5 + docs/{customize => components}/custom-css.md | 0 docs/{customize => components}/download.md | 0 docs/components/index.md | 10 + docs/components/logo.md | 7 + .../{customize => components}/source-files.md | 2 +- docs/conf.py | 17 +- docs/{ => content}/content-blocks.md | 8 +- docs/content/index.md | 9 + docs/{ => content}/launch.md | 0 docs/{ => content}/notebooks.md | 2 +- docs/contributing/index.md | 2 +- docs/customize/header.md | 30 --- docs/index.md | 18 +- docs/{customize/index.md => reference.md} | 24 +- docs/{customize => sections}/announcements.md | 0 .../{customize => sections}/footer-content.md | 2 +- docs/sections/footer.md | 21 ++ docs/sections/header.md | 46 ++++ docs/sections/index.md | 12 + .../sidebar-primary.md | 20 +- .../sidebar-secondary.md | 2 +- pyproject.toml | 4 +- src/sphinx_book_theme/__init__.py | 8 +- src/sphinx_book_theme/assets/scripts/index.js | 10 - .../assets/styles/abstracts/_mixins.scss | 9 + .../assets/styles/abstracts/_variables.scss | 12 +- .../assets/styles/base/_base.scss | 6 +- .../assets/styles/base/_print.scss | 12 +- .../assets/styles/components/_logo.scss | 19 ++ .../styles/components/_primary-nav.scss | 11 + .../assets/styles/components/_search.scss | 14 +- .../assets/styles/content/_margin.scss | 2 +- .../assets/styles/index.scss | 2 + .../styles/sections/_article-container.scss | 4 + .../styles/sections/_footer-article.scss | 4 + .../styles/sections/_header-article.scss | 101 ++++++--- .../styles/sections/_header-primary.scss | 27 ++- .../styles/sections/_sidebar-primary.scss | 30 +-- .../styles/sections/_sidebar-secondary.scss | 35 ++- .../header_buttons/__init__.py | 29 ++- .../header_buttons/launch.py | 18 +- .../components/article-header-buttons.html | 15 ++ .../components/sidebar-icons.html | 0 .../components/toggle-primary-sidebar.html | 3 + .../components/toggle-secondary-sidebar.html | 7 + .../theme/sphinx_book_theme/layout.html | 3 - .../sphinx_book_theme/macros/buttons.html | 11 +- .../sections/header-article.html | 22 -- .../theme/sphinx_book_theme/theme.conf | 43 +++- tests/test_build.py | 6 +- tests/test_build/build__header-article.html | 206 ++++++++++-------- .../build__pagetoc--page-multipletitles.html | 68 +++--- .../build__pagetoc--page-onetitle.html | 40 ++-- ...ild__pagetoc--page-onetitlenoheadings.html | 2 - .../build__sidebar-primary__nav.html | 90 -------- .../header__repo-buttons--all-off.html | 90 +++++--- .../header__repo-buttons--all-on.html | 152 +++++++------ .../header__repo-buttons--custom-branch.html | 136 +++++++----- .../header__repo-buttons--one-on.html | 102 +++++---- tests/test_build/test_header_launchbtns.html | 84 +++---- .../test_build/test_right_sidebar_title.html | 2 +- 67 files changed, 985 insertions(+), 714 deletions(-) create mode 100644 docs/_static/logo-square.png create mode 100644 docs/_static/logo-wide-dark.svg delete mode 100644 docs/_templates/sections/header.html create mode 100644 docs/_templates/test.html rename docs/{customize => components}/custom-css.md (100%) rename docs/{customize => components}/download.md (100%) create mode 100644 docs/components/index.md create mode 100644 docs/components/logo.md rename docs/{customize => components}/source-files.md (98%) rename docs/{ => content}/content-blocks.md (98%) create mode 100644 docs/content/index.md rename docs/{ => content}/launch.md (100%) rename docs/{ => content}/notebooks.md (99%) delete mode 100644 docs/customize/header.md rename docs/{customize/index.md => reference.md} (79%) rename docs/{customize => sections}/announcements.md (100%) rename docs/{customize => sections}/footer-content.md (96%) create mode 100644 docs/sections/footer.md create mode 100644 docs/sections/header.md create mode 100644 docs/sections/index.md rename docs/{customize => sections}/sidebar-primary.md (82%) rename docs/{customize => sections}/sidebar-secondary.md (96%) create mode 100644 src/sphinx_book_theme/assets/styles/components/_logo.scss create mode 100644 src/sphinx_book_theme/assets/styles/components/_primary-nav.scss create mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/components/article-header-buttons.html delete mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/components/sidebar-icons.html create mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-primary-sidebar.html create mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html delete mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/sections/header-article.html delete mode 100644 tests/test_build/build__pagetoc--page-onetitlenoheadings.html delete mode 100644 tests/test_build/build__sidebar-primary__nav.html diff --git a/.github/workflows/lighthouserc.json b/.github/workflows/lighthouserc.json index 495f3d93..52f5daa6 100644 --- a/.github/workflows/lighthouserc.json +++ b/.github/workflows/lighthouserc.json @@ -9,9 +9,9 @@ }, "assert": { "assertions": { - "categories:performance": ["error", { "minScore": 0.84 }], - "categories:accessibility": ["error", { "minScore": 0.84 }], - "categories:best-practices": ["error", { "minScore": 0.84 }] + "categories:performance": ["error", { "minScore": 0.8 }], + "categories:accessibility": ["error", { "minScore": 0.8 }], + "categories:best-practices": ["error", { "minScore": 0.8 }] } } } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 354371f1..0757b1c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -See [the contributing documentation](./docs/contributing/index.md). +See [the contributing documentation](https://sphinx-book-theme.readthedocs.io/en/stable/contributing/index.html). diff --git a/docs/_static/logo-square.png b/docs/_static/logo-square.png new file mode 100644 index 0000000000000000000000000000000000000000..5a83568fffc67fe6ed040062606c83ced8e21760 GIT binary patch literal 2620 zcmV-C3d8k@P)L*Sj5yU9@q;B#AE3ZWY_rOeS-|%bPN~7mJ49A=*x2gQtxS(ON}2 zCB)EC?WC##5XOh$_YoUD?R1E?Ux=W!(u)-ZAdLS#6?#2m4~K;ac9lOlOaQ|8C&i(K z7#nF7BG_E|M7H#YV$W|O##UO2HXdYf1Q0K@h{H)@Tws?N2@d0d6o4@PbaD8V3e!8r zelTU6AwV$DXU|f1cQ>UG zT$_y>H~M-{BZcJNy?b>3{(XvzS+izIAuL?;lhO!CHPD~oj`$Ua8xsu)W!g~a9g)-mAwJe9}^Hk7;2Go2uhUS zCG|ldj1Li*rhb?z`f(lQpw}e@FM{`qHM0ODKui|~aY<03yy#&;z9TBE5di$@mMvSf z=Y$bJlovfLJOWe!ae*#M$4nwP{OI*)y67Ltog`)Ql0<9*fWd;MWzpji?4cOMOJ0O zgW8VutAPkK_wL=xqd^s7ivi%P!|V&daF6LA_5;GmIs@YzR1WXkw~u3kGEzGNs7)1! z_F-HUgzAz#5D4M|W+>LU0PInO&)10nRl&8)J){wW zRsg2@e-=OiXGZ|0fVBd^{e&1Z)(YU|%a_EMu~qjbW0MOiokJ`DR_ z{%{3$3Gwj%hE#4118RGiI(orWE8rrb|7MUfq$En73S^x(R9*p&G26>^@#&2(LrxPbmP?XebQ>*p2i9>Y|hJ7vvuZ*<7Qj!+Rr@0x10>k_ehq@We* z5)%)wNAB3?@^Ry$b<{X_B{jaklKi3-K)&-ay}EX4(C9iH z`mUcJ@*Hf^F!y5`v1mOt%v|E>bF?mCKnS3({nRky13cH)-bzgULB}jNzIIeMJoWP2&$?^U;AnKWtjTXBYM9MxC5^kgFyI~YCv(hGuw!%AFtYe6#oB@s;_4! z&7sWrDdZKi01RrvaAQ&=6Ag&^U$yD~FviH`o5&AF0l*EI0t)yYh#>5ggsBc%ohIv0=I2s|u&@gi;i@^gh`s>@5AAv4>epJ)yNH&HbM}Uhskb*2=xjX2;(OSkAbe-!Hj*yfsC#`Wk#7xCLO>Lq)C-FX3Ll#E*$loX zdcEHT9zWD{Zy;Pl|Lry@hNMN-qcb-$-G3Zl&y%_It#rVMb&7mWfZSuZL20q`h?QTx&4)(fdE{lyYj+L&tA%Ml} zJe}vI`q?&|5I`ZrHph6L&C|VVICF!DhDrK+2)bIe?9LrRG@D#O)=>dif3s*s!+T4# z3sTt_OU&a0iJ(q#97l|cbioC55aTMhAb_jHxXND;zy)Gl + + + + + + + + + + + + diff --git a/docs/_templates/sections/header.html b/docs/_templates/sections/header.html deleted file mode 100644 index 6630c176..00000000 --- a/docs/_templates/sections/header.html +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/docs/_templates/test.html b/docs/_templates/test.html new file mode 100644 index 00000000..bc9ca840 --- /dev/null +++ b/docs/_templates/test.html @@ -0,0 +1,5 @@ +{# This is a test template to try out insertion in the header. + You can un-comment the line that adds this to our header in `conf.py` +#} + + diff --git a/docs/customize/custom-css.md b/docs/components/custom-css.md similarity index 100% rename from docs/customize/custom-css.md rename to docs/components/custom-css.md diff --git a/docs/customize/download.md b/docs/components/download.md similarity index 100% rename from docs/customize/download.md rename to docs/components/download.md diff --git a/docs/components/index.md b/docs/components/index.md new file mode 100644 index 00000000..b9bdee3f --- /dev/null +++ b/docs/components/index.md @@ -0,0 +1,10 @@ +# Component customization + +Components are specific UI elements that you can control with configuration. + +```{toctree} +logo +download +source-files +custom-css +``` diff --git a/docs/components/logo.md b/docs/components/logo.md new file mode 100644 index 00000000..14d38472 --- /dev/null +++ b/docs/components/logo.md @@ -0,0 +1,7 @@ + +(sidebar-primary:logo)= +# Logo and branding + +You can customize the logo, title, and favicon of your site. + +This theme uses the same configuration as the `pydata-sphinx-theme`, so refer to {external:doc}`the PyData Sphinx Theme branding documentation `. diff --git a/docs/customize/source-files.md b/docs/components/source-files.md similarity index 98% rename from docs/customize/source-files.md rename to docs/components/source-files.md index 811a8f24..2c0958b7 100644 --- a/docs/customize/source-files.md +++ b/docs/components/source-files.md @@ -1,5 +1,5 @@ (customize:source-files)= -# Add buttons to link to your source +# Buttons that link to source files There are a collection of buttons that you can use to link back to your source repository. This lets users browse the repository, or take actions like suggest diff --git a/docs/conf.py b/docs/conf.py index b88a1fe3..4e1247ad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -121,19 +121,30 @@ "use_repository_button": True, "use_download_button": True, "use_sidenotes": True, - "logo": { - "text": html_title, - }, "show_toc_level": 2, "announcement": ( "⚠️The latest release refactored our HTML, " "so double-check your custom CSS rules!⚠️" ), + "logo": { + "image_dark": "_static/logo-wide-dark.svg", + } # For testing # "use_fullscreen_button": False, # "home_page_in_toc": True, # "extra_footer": "Test", # DEPRECATED KEY # "show_navbar_depth": 2, + # Testing layout areas + # "navbar_start": ["test.html"], + # "navbar_center": ["test.html"], + # "navbar_end": ["test.html"], + # "footer_start": ["test.html"], + # "footer_end": ["test.html"] +} + +# sphinxext.opengraph +ogp_social_cards = { + "image": "_static/logo-square.png", } # -- ABlog config ------------------------------------------------- diff --git a/docs/content-blocks.md b/docs/content/content-blocks.md similarity index 98% rename from docs/content-blocks.md rename to docs/content/content-blocks.md index 23f80230..0805c435 100644 --- a/docs/content-blocks.md +++ b/docs/content/content-blocks.md @@ -158,7 +158,7 @@ Here is a figure with a caption to the right. ::::{example} :no-container: -```{figure} images/cool.jpg +```{figure} ../images/cool.jpg --- width: 60% figclass: margin-caption @@ -199,7 +199,7 @@ some vertical space to see better. :no-container: :reverse: -```{figure} images/cool.jpg +```{figure} ../images/cool.jpg --- figclass: margin alt: My figure text @@ -237,7 +237,7 @@ print("here is some python") ````{margin} **Notes in margins** ```{note} Wow, a note with an image in a margin! -![](images/cool.jpg) +![](../images/cool.jpg) ``` ```` ````` @@ -256,7 +256,7 @@ To add content sidebars, use this syntax: ```{note} Here is my sidebar content, it is pretty cool! ``` -![](images/cool.jpg) +![](../images/cool.jpg) ```` ````` diff --git a/docs/content/index.md b/docs/content/index.md new file mode 100644 index 00000000..78c5b3a3 --- /dev/null +++ b/docs/content/index.md @@ -0,0 +1,9 @@ +# Content and formatting + +These sections describe content-specific customization and formatting. + +```{toctree} +content-blocks +notebooks +launch +``` diff --git a/docs/launch.md b/docs/content/launch.md similarity index 100% rename from docs/launch.md rename to docs/content/launch.md diff --git a/docs/notebooks.md b/docs/content/notebooks.md similarity index 99% rename from docs/notebooks.md rename to docs/content/notebooks.md index a8530c97..ea2e8f3e 100644 --- a/docs/notebooks.md +++ b/docs/content/notebooks.md @@ -22,7 +22,7 @@ This page demonstrates some extra functionality that works with this theme. As it is markdown, you can embed images, HTML, etc into your posts! -![](./images/cool.jpg) +![](../images/cool.jpg) You an also $add_{math}$ and diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 94ac37d8..4731b72b 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -3,7 +3,7 @@ Thank you for being interested in contributing to the `sphinx-book-theme`! You are awesome ✨. -This project follows the Executable Books Project [contribution guidelines](https://executablebooks.org/en/latest/contribute.html). +This project follows the Executable Books Project [contribution guidelines](https://executablebooks.org/en/latest/contribute). It contains information about our conventions around coding style, pull request workflow, commit messages and more. The rest of these sections contain information about developing the `sphinx-book-theme` specifically. diff --git a/docs/customize/header.md b/docs/customize/header.md deleted file mode 100644 index 0dc58c2b..00000000 --- a/docs/customize/header.md +++ /dev/null @@ -1,30 +0,0 @@ -# Header content - -By default, this theme does not contain any header content, it only has a sidebar and a main content window. -However, you can define your own HTML in a header that will be inserted **above everything else**. -To do so, you must define your own Sphinx Template in a specific location. -The contents of this template will be inserted into the theme. -Here is how to do this: - -- Create a templates folder in your theme's root. Assuming your documentation is in the `docs/` folder: - - ```console - $ cd docs/ - $ mkdir _templates - ``` -- Add the `_templates/` folder to your Sphinx configuration templates: - - ```python - templates_path = ["_templates"] - ``` -- Create the following template file and add HTML to id: - - ```console - $ echo "

Some text!

" > _templates/sections/header.html - ``` -- Build your documentation, and you should see content of this file show up above your site. - -## Style the header - -Note that the header has very little styling applied to it by default. -So you should [add custom styles to the theme](custom-css.md) in order to achieve the look and feel you want. diff --git a/docs/index.md b/docs/index.md index d22c5d7b..27839f64 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ A Sphinx theme with a clean design, support for interactive content, and a moder [Visual classes designed for Jupyter Notebooks](reference/notebooks) : Cell inputs, outputs, and interactive functionality are all supported. -[Launch buttons for online interactivity](launch) +[Launch buttons for online interactivity](content/launch) : For pages that are built with computational material, connect your site to an online BinderHub for interactive content. [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) @@ -52,19 +52,20 @@ The following topic areas will help you understand and use the theme. :caption: Topic Areas tutorials/get-started -customize/index -content-blocks -notebooks -launch +content/index +sections/index +components/index +reference contributing/index +changelog ``` -# Reference pages +# Example pages -Reference pages demonstrate the visual look of this theme. +Examples pages demonstrate the visual look of this theme. ```{toctree} -:caption: Reference +:caption: Example pages :maxdepth: 2 reference/kitchen-sink/index @@ -75,7 +76,6 @@ reference/thebe reference/blog reference/api-numpy reference/comments -changelog ``` # Inspiration diff --git a/docs/customize/index.md b/docs/reference.md similarity index 79% rename from docs/customize/index.md rename to docs/reference.md index 018daa76..f03604f6 100644 --- a/docs/customize/index.md +++ b/docs/reference.md @@ -1,10 +1,11 @@ -# Customization -These sections describe a few ways that you may customize the look and feel of your theme. +# Reference of theme options -## Theme options +The following theme-specific options are available via `html_theme_options`. -The following options are available via `html_theme_options` +```{admonition} See the PyData Theme as well +These are **in addition to** all of the {external:doc}`options available in the PyData Sphinx Theme `. +``` ```{list-table} :widths: 10 5 40 @@ -49,18 +50,3 @@ The following options are available via `html_theme_options` - str - The text to be displayed with the in-page TOC (`Contents` is default) ``` - -## Customization Topics - -The following sections describe a few ways to customize the theme in more depth. - -```{toctree} -sidebar-primary.md -sidebar-secondary.md -footer-content.md -announcements.md -header.md -download.md -source-files.md -custom-css.md -``` diff --git a/docs/customize/announcements.md b/docs/sections/announcements.md similarity index 100% rename from docs/customize/announcements.md rename to docs/sections/announcements.md diff --git a/docs/customize/footer-content.md b/docs/sections/footer-content.md similarity index 96% rename from docs/customize/footer-content.md rename to docs/sections/footer-content.md index 80ef2efc..37a31979 100644 --- a/docs/customize/footer-content.md +++ b/docs/sections/footer-content.md @@ -1,4 +1,4 @@ -# Customize the content footer +# Content footer There is a content footer that spans the width of the page, and is visibile when you scroll to the bottom of the content. diff --git a/docs/sections/footer.md b/docs/sections/footer.md new file mode 100644 index 00000000..0155ec04 --- /dev/null +++ b/docs/sections/footer.md @@ -0,0 +1,21 @@ +# Page footer + +The page footer spans the entire width of the page, and is only visible once you scroll to the end of the article's content. + +By default, it is empty and not visible. +However, there are two configuration points where you can add items to your footer: + +`html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the beginning (left on most screens) of the footer. + +`html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the end (right on most screens) of the footer. + +For example, the configuration below assumes there is a template at `_templates/test.html`. +It adds the `_templates` folder to Sphinx's templates path, and adds the template to both the start and end section of the footer. + +```python +templates_path = ["_templates"] +html_theme_options = { + "footer_start": ["test.html"], + "footer_end": ["test.html"] +} +``` diff --git a/docs/sections/header.md b/docs/sections/header.md new file mode 100644 index 00000000..767a1fca --- /dev/null +++ b/docs/sections/header.md @@ -0,0 +1,46 @@ +# Header and navbar + +By default, this theme does not contain any header content, it only has a sidebar and a main content window. +However, you may [use the PyData Sphinx Theme's header configuraiton](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#header-navigation-bar) to add your own header components. +If any of this configuration is set, then your header will show at the top of the page. + +## Add components to the header navbar + +There are three configuration options you can use in `html_theme_options`: + +**`navbar_start`**: Adds components to the beginning of the header. **Visible on all screen sizes**. Use this for adding a logo that you want to persist over time. + +**`navbar_center`**: Adds components to the center of the header, or to the left if no `navbar_start` is defined. **Moved to the sizebar on mobile**. Use this for extra navigation content to external pages. + +**`navbar_end`**: Adds components to the end of the header. **Moved to the sizebar on mobile**. Use this for extra social links or buttons. + +## An eample + +For example, you can add a button to the header like so: + +**Create a HTML template**. In `_templates/mybutton.html`, put the following text: + +```html + +``` + +Make sure that `_templates` is [on your templates path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path). + +**Add the following to `conf.py`**: + +```python +html_theme_options = { + "navbar_end": ["mybutton.html"] +} +``` + +Your header should now be visible, and the `mybutton.html` content should now show up in the upper-right. + +:::{admonition} Override the entire header +Alternatively, you can over-ride the entire header by defining a file at `_templates/sections/header.html`. +::: + +## Style the header + +Note that the header has very little styling applied to it by default. +So you should [add custom styles to the theme](../components/custom-css.md) in order to achieve the look and feel you want. diff --git a/docs/sections/index.md b/docs/sections/index.md new file mode 100644 index 00000000..a8128758 --- /dev/null +++ b/docs/sections/index.md @@ -0,0 +1,12 @@ +# Layout and major sections + +These sections describe how to add content to the major sections of the site. + +```{toctree} +sidebar-primary +sidebar-secondary +header +footer-content +footer +announcements +``` diff --git a/docs/customize/sidebar-primary.md b/docs/sections/sidebar-primary.md similarity index 82% rename from docs/customize/sidebar-primary.md rename to docs/sections/sidebar-primary.md index d025c520..2f67e8ed 100644 --- a/docs/customize/sidebar-primary.md +++ b/docs/sections/sidebar-primary.md @@ -1,4 +1,4 @@ -# Customize the primary sidebar +# Primary sidebar and navigation The primary sidebar generally contains the site navigation and logo. By default it is on the left side of the site. @@ -37,29 +37,11 @@ By default, this theme comes with these three theme-specific sidebar elements en - `search-field.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/)) - `sbt-sidebar-nav.html`: A bootstrap-based navigation menu for your book. - ## Add a header to your Table of Contents If you'd like to add a header above a section of TOC links, use `:caption: My header text` in your `toctree` directive for that section. -(sidebar-primary:logo)= -## Customize the logo, title, and favicon - -You can customize the logo, title, and favicon of your site with the following Sphinx configuration in `conf.py`: - -```python -html_title = "Your title" -html_logo = "path/to/logo.png" -html_favicon = "path/to/favicon.ico" -``` - -These will be placed in the top-left of your page. - -Alternatively you can use the `logo` field in `html_theme_options` to have more control over your logo. - -For more details, see the {external:doc}`PyData Sphinx Theme `. - (sidebar-primary:home-page)= ## Add the home page to your table of contents diff --git a/docs/customize/sidebar-secondary.md b/docs/sections/sidebar-secondary.md similarity index 96% rename from docs/customize/sidebar-secondary.md rename to docs/sections/sidebar-secondary.md index d2157f6d..495af2b9 100644 --- a/docs/customize/sidebar-secondary.md +++ b/docs/sections/sidebar-secondary.md @@ -1,4 +1,4 @@ -# Customize the secondary sidebar +# Secondary sidebar and table of contents The secondary sidebar contains information about the current page. It begins at the top of the page (in the header), and extends downwards (by default, from the right side of the page). diff --git a/pyproject.toml b/pyproject.toml index bdaac1f5..3d7bb6ed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ readme = "README.md" requires-python = ">=3.7" dependencies = [ "sphinx>=4,<7", - "pydata-sphinx-theme", + "pydata-sphinx-theme>=0.13.0rc3", ] license = { file = "LICENSE" } @@ -68,7 +68,7 @@ doc = [ "sphinxext-opengraph", ] test = [ - "beautifulsoup4>=4.6.1,<5", + "beautifulsoup4", "coverage", "myst-nb", "pytest", diff --git a/src/sphinx_book_theme/__init__.py b/src/sphinx_book_theme/__init__.py index 4d673034..58854270 100644 --- a/src/sphinx_book_theme/__init__.py +++ b/src/sphinx_book_theme/__init__.py @@ -117,6 +117,8 @@ def update_mode_thebe_config(app): """Update thebe configuration with SBT-specific values""" theme_options = app.env.config.html_theme_options if theme_options.get("launch_buttons", {}).get("thebe") is True: + # In case somebody specifies they want thebe in a launch button + # but has not activated the sphinx_thebe extension. if not hasattr(app.env.config, "thebe_config"): SPHINX_LOGGER.warning( ( @@ -146,12 +148,6 @@ def update_mode_thebe_config(app): app.env.config.thebe_config = thebe_config - # setting default mode to light for now. - # TODO: provide a button, and add css for dark theme. - # sphinx-build command does not call config-inited, - # so setting this in builder-inited. - app.config.html_context["default_mode"] = "light" - def check_deprecation_keys(app): """Warns about the deprecated keys.""" diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index 1b4458b8..adc3e6c1 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -167,16 +167,6 @@ function addNoPrint() { document.querySelector("footer.bd-footer-article").classList.add("noprint"); } -/** - * Set Mode of the theme - * Remove this function once all modes are supported. - */ - -function setMode() { - document.documentElement.dataset.mode = "light"; - document.documentElement.dataset.theme = "light"; -} - /** * Set up callback functions for UI click actions */ diff --git a/src/sphinx_book_theme/assets/styles/abstracts/_mixins.scss b/src/sphinx_book_theme/assets/styles/abstracts/_mixins.scss index c93f19c0..38ec9558 100644 --- a/src/sphinx_book_theme/assets/styles/abstracts/_mixins.scss +++ b/src/sphinx_book_theme/assets/styles/abstracts/_mixins.scss @@ -12,3 +12,12 @@ } } } + +/** + * The PyData Sphinx Theme box shadow rule + * Copied here in csae we need to re-use. +*/ +@mixin pst-box-shadow() { + box-shadow: 0 0.2rem 0.5rem var(--pst-color-shadow), + 0 0 0.0625rem var(--pst-color-shadow) !important; +} diff --git a/src/sphinx_book_theme/assets/styles/abstracts/_variables.scss b/src/sphinx_book_theme/assets/styles/abstracts/_variables.scss index 7d96abb1..e47b0a02 100644 --- a/src/sphinx_book_theme/assets/styles/abstracts/_variables.scss +++ b/src/sphinx_book_theme/assets/styles/abstracts/_variables.scss @@ -12,6 +12,17 @@ $zindex-bottom: 1; $zindex-middle: 2; $zindex-top: 3; +// Semantic Z-index from bootstrap. Copied here so we can re-use if needed. +// ref: https://getbootstrap.com/docs/5.0/layout/z-index/ +$zindex-dropdown: 1000; +$zindex-sticky: 1020; +$zindex-fixed: 1030; +$zindex-modal-backdrop: 1040; +$zindex-offcanvas: 1050; +$zindex-modal: 1060; +$zindex-popover: 1070; +$zindex-tooltip: 1080; + // Spacing $header-article-height: 3rem; $sidebar-primary-width-widescreen: 20%; @@ -31,7 +42,6 @@ $sbt-font-size-small-1: 87.5%; html { // Over-ride the pydata theme so that readers can use their system base --pst-font-size-base: none; - --pst-header-height: 0px; } // Overrides for pydata sphinx theme. diff --git a/src/sphinx_book_theme/assets/styles/base/_base.scss b/src/sphinx_book_theme/assets/styles/base/_base.scss index e9514d50..133dd494 100644 --- a/src/sphinx_book_theme/assets/styles/base/_base.scss +++ b/src/sphinx_book_theme/assets/styles/base/_base.scss @@ -25,7 +25,10 @@ html { display: none; } -// Print-specific utility classes +/** + * Printing behavior + */ +// Only display upon printing .onlyprint { display: none; @@ -34,6 +37,7 @@ html { } } +// Prevent an item from being printed .noprint { @media print { display: none !important; diff --git a/src/sphinx_book_theme/assets/styles/base/_print.scss b/src/sphinx_book_theme/assets/styles/base/_print.scss index 8b240980..1e90cdf6 100644 --- a/src/sphinx_book_theme/assets/styles/base/_print.scss +++ b/src/sphinx_book_theme/assets/styles/base/_print.scss @@ -4,7 +4,7 @@ @media print { .bd-main { .bd-content { - margin-left: 3rem; + margin-left: 2rem; height: auto; // Structural elements #jb-print-docs-body { @@ -56,7 +56,10 @@ display: none; } - blockquote.epigraph { + // Remove borders to save some ink + blockquote.epigraph, + aside.margin, + aside.sidebar { border: none; } @@ -83,5 +86,10 @@ } } } + + // Hide the footer on printing + .bd-footer-content { + display: none !important; + } } } diff --git a/src/sphinx_book_theme/assets/styles/components/_logo.scss b/src/sphinx_book_theme/assets/styles/components/_logo.scss new file mode 100644 index 00000000..38f597cd --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/components/_logo.scss @@ -0,0 +1,19 @@ +.navbar-brand { + height: unset; + max-height: unset; + + // Auto-center the image and title and make items vertical + flex-direction: column; + justify-content: center; + gap: 0.25rem; + + // To prevent site text from having underlines + &:hover { + text-decoration: none; + } + .logo__title { + font-size: 1.25rem; + white-space: normal; + text-align: center; + } +} diff --git a/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss b/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss new file mode 100644 index 00000000..75137a72 --- /dev/null +++ b/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss @@ -0,0 +1,11 @@ +/** + * Primary navigation links in the sidebar + */ + +// UPSTREAM +.bd-sidenav { + // Prevent really long words from spilling out of sidebar + li { + word-wrap: break-word; + } +} diff --git a/src/sphinx_book_theme/assets/styles/components/_search.scss b/src/sphinx_book_theme/assets/styles/components/_search.scss index eaae68b4..9c254493 100644 --- a/src/sphinx_book_theme/assets/styles/components/_search.scss +++ b/src/sphinx_book_theme/assets/styles/components/_search.scss @@ -1,15 +1,15 @@ +// Clean up the search page so that it has less unnecessary text .bd-search-container { margin: 2em; - // Remove the search field on the search page since we have one in the sidebar - h1:first-child { - display: none; - } + #search-results { h2:first-child { display: none; } } - .bd-search { - display: none !important; - } +} + +// Make the search buttons smaller so that it is centered properly +.search-button i { + font-size: 1.1rem; } diff --git a/src/sphinx_book_theme/assets/styles/content/_margin.scss b/src/sphinx_book_theme/assets/styles/content/_margin.scss index 23a37182..a6a23157 100644 --- a/src/sphinx_book_theme/assets/styles/content/_margin.scss +++ b/src/sphinx_book_theme/assets/styles/content/_margin.scss @@ -32,7 +32,7 @@ $margin-offset: -$margin-width-relative-to-content; margin-left: 0.5rem; // This is the wide-screen behavior - @media (min-width: $breakpoint-lg) { + @media (min-width: $breakpoint-lg), print { width: $margin-width-width-gutter; margin: 0 $margin-offset 0 0; diff --git a/src/sphinx_book_theme/assets/styles/index.scss b/src/sphinx_book_theme/assets/styles/index.scss index ab7be4b2..39da0e0f 100644 --- a/src/sphinx_book_theme/assets/styles/index.scss +++ b/src/sphinx_book_theme/assets/styles/index.scss @@ -27,6 +27,8 @@ @import "sections/footer-article"; // Re-usable components across the theme +@import "components/logo"; +@import "components/primary-nav"; @import "components/search"; // Content blocks in standard Sphinx diff --git a/src/sphinx_book_theme/assets/styles/sections/_article-container.scss b/src/sphinx_book_theme/assets/styles/sections/_article-container.scss index 4cbe4c71..66c405f5 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_article-container.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_article-container.scss @@ -8,6 +8,10 @@ .bd-article { padding-right: 2rem; padding-left: 2rem; + @media (max-width: $breakpoint-md) { + padding-right: 1rem; + padding-left: 1rem; + } } details.above-input, details.below-input { diff --git a/src/sphinx_book_theme/assets/styles/sections/_footer-article.scss b/src/sphinx_book_theme/assets/styles/sections/_footer-article.scss index 1d2e412e..ac340be2 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_footer-article.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_footer-article.scss @@ -1,3 +1,7 @@ .bd-footer-article { padding: 0rem 1rem; + @media (max-width: $breakpoint-md) { + // More room for text on mobile + padding: 0rem 0.5rem; + } } diff --git a/src/sphinx_book_theme/assets/styles/sections/_header-article.scss b/src/sphinx_book_theme/assets/styles/sections/_header-article.scss index bd0fdbf1..d4065b18 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_header-article.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_header-article.scss @@ -7,7 +7,7 @@ */ @mixin header-height-mobile { @media (max-width: $breakpoint-md) { - height: $header-article-height + 0.75rem; + height: $header-article-height + 0.5rem; } } @@ -36,49 +36,62 @@ label.sidebar-toggle.secondary-toggle { // Wrapper container .bd-header-article { - height: $header-article-height; // Fix the height so the TOC doesn't grow it + display: flex; + align-items: center; + position: sticky; + top: 0; background-color: var(--pst-color-background); transition: left 0.2s; font-size: 0.9em; - position: sticky; - top: 0; padding: 0 1rem; - z-index: 1018; + + @media (max-width: $breakpoint-md) { + // Give mobile view a bit more space for text + padding: 0 0.5rem; + } + z-index: $zindex-sticky; @include header-height-mobile; + // The box shadow that shows up when you've scrolled past the top .scrolled & { box-shadow: 0 6px 6px -6px var(--pst-color-shadow); } - // Inner container with content - .header-article-main { + // Remove inner padding so that spacing of buttons is a bit tighter + .header-article__inner { + padding: 0; + } + + // Inner container with items in it + .header-article-items { + display: flex; + align-items: center; height: $header-article-height; - @include header-height-mobile; - padding: 0 !important; // Override bootstrap default + width: 100%; + } - .header-article__left, - .header-article__right { - display: flex; - align-items: center; - } + // Contains the individual item components so we want it centered + .header-article-item { + display: flex; + align-items: center; + } - .header-article__right { - margin-left: auto; - } + /** + * Buttons in the header + */ + // A series of buttons we special-case in the theme + .article-header-buttons { + display: flex; } -} -/** - * Buttons in the header - */ -div.header-article-main { + // Generic button styles .btn { // Basic button size font-size: 1.3rem; color: var(--pst-color-text-muted); border: none; - padding: 0 0.75rem; + padding: 0 0.5rem; // Hover / active behavior &.show, @@ -101,14 +114,49 @@ div.header-article-main { } } + .theme-switch-button { + // Removing some special-casing that was needed in PST + margin: 0; + + // Remove extra padding since it is already there between sidebar items + span, + i, + button { + padding: 0; + } + + // No background on hover. Need important to over-ride the PST which uses it too. + span, + i { + transition: color $animation-time ease-out; + } + &:active, + &:hover { + background-color: unset !important; + span, + i { + color: var(--pst-color-text-base); + } + } + } + // The menu that is normally hidden until you hover .dropdown-menu { - // Positioning and layout of dropdown items to be standardized - margin-top: 0px; - transform: translateX(-75%); + // Hidden unless we are hovering &:hover { display: block; } + + // Positioning and layout of dropdown items to be standardized + margin-top: 0px; + transform: translateX(-75%); + @include pst-box-shadow; + + // Color and shadowing + border-color: var(--pst-color-border); + background-color: var(--pst-color-background); + color: var(--pst-color-text-muted); + .dropdown-item { display: inline-flex; align-items: center; @@ -118,6 +166,7 @@ div.header-article-main { &:hover { text-decoration: none; background-color: initial; + color: var(--pst-color-text-base); } // Slightly smaller font for everything diff --git a/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss index 94fd454d..f1fc635c 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss @@ -1,3 +1,28 @@ .bd-header { - display: none; + // Turn off sticky positioning so that it scrolls + position: inherit; + + // Turn these off because we'll show it in the article header + // The primary sidebar toggle + label.sidebar-toggle { + display: none; + } + + // This contains the search button that shows up on mobile + .navbar-header-items .navbar-persistent--container { + display: none; + } + .navbar-persistent--mobile { + display: none; + } + + // UPSTREAM to fix this bug + // These rules are applied too-selectively in the PST so they don't apply + // to the `navbar_start` items. This just applies the same rule to *all* items. + .navbar-item { + align-items: center; + display: flex; + height: var(--pst-header-height); + max-height: var(--pst-header-height); + } } diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss index 3caad9f7..09b32d91 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss @@ -3,34 +3,34 @@ *********************************************/ .bd-sidebar-primary { + // So that it sticks to the top of the page instead of the header height + top: 0; + max-height: 100vh; + transition: margin-left $animation-time ease 0s, opacity $animation-time ease 0s, visibility $animation-time ease 0s; - font-size: $sbt-font-size-small-1; - .navbar-brand { - height: unset; - // Auto-center the image and title and make items vertical - flex-direction: column; - justify-content: center; - } + // To prevent a phantom gap when there's no header + gap: 0; .bd-search input { // Slightly reduce padding because it's a bit too big on this theme padding-left: 2rem; } - // Remove the header items that pop into the sidebar in the pydata theme - .sidebar-header-items { - display: none; + // Remove the top border since there's often no header items above + .sidebar-primary-items__start { + border-top: none; } - // Remove the top border since there's no header items above - .sidebar-start-items { - border-top: none; + // Tighter spacing in the sidebar than the PST + .sidebar-start-items__item, + .sidebar-end-items__item { + padding: 0.25rem 0; } // On wide screens we have a smaller sidebar width than PST - @media (min-width: $breakpoint-md) { + @media (min-width: $breakpoint-lg) { flex-basis: $sidebar-primary-width-widescreen; } } @@ -38,7 +38,7 @@ // Default visibility for left sidebar is the reverse of what it is on mobile. // It is shown by default, and hidden with a click. // Mobile behavior is defined in the pydata sphinx theme -@media (min-width: $breakpoint-md) { +@media (min-width: $breakpoint-lg) { input#__primary:checked ~ .bd-container .bd-sidebar-primary { margin-left: -$sidebar-primary-width-widescreen; visibility: hidden; diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss index 4dfa6475..7fb9013b 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss @@ -3,8 +3,34 @@ *********************************************/ .bd-sidebar-secondary { + // So that it sticks to the top of the page instead of the header height + top: 0; + + // So that we can center the TOC button with the article header buttons + .sidebar-secondary-items { + padding: 0; + display: flex; + gap: 0.5rem; + + // Remove the manual padding since we'll use `gap` + .sidebar-secondary-item { + padding-top: 0; + padding-bottom: 0; + } + } + + // The 'on this page' title div should take up the full header + .onthispage { + height: $header-article-height; + min-height: $header-article-height; + display: flex; + align-items: center; + margin: 0; + color: var(--pst-color-muted); + } + // Wide screen behavior - @media (min-width: $breakpoint-md) { + @media (min-width: $breakpoint-lg) { background: var(--pst-color-background); height: fit-content; transition: max-height 0.4s ease; @@ -22,13 +48,6 @@ // Flush with the top so that we can fix the height of the toc header div padding-top: 0; - // The 'on this page' title div should take up the full header - .onthispage { - height: $header-article-height; - display: flex; - align-items: center; - } - // The table of contents
    after the title div nav.page-toc { // Remove extra margin the PST adds for other sidebar items diff --git a/src/sphinx_book_theme/header_buttons/__init__.py b/src/sphinx_book_theme/header_buttons/__init__.py index 3fe157dd..cf36d137 100644 --- a/src/sphinx_book_theme/header_buttons/__init__.py +++ b/src/sphinx_book_theme/header_buttons/__init__.py @@ -1,6 +1,10 @@ """Generate metadata for header buttons.""" from sphinx.errors import SphinxError +from sphinx.locale import get_translation + +MESSAGE_CATALOG_NAME = "booktheme" +translation = get_translation(MESSAGE_CATALOG_NAME) def _as_bool(var): @@ -38,7 +42,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): { "type": "javascript", "javascript": "toggleFullScreen()", - "tooltip": "Fullscreen mode", + "tooltip": translation("Fullscreen mode"), "icon": "fas fa-expand", } ) @@ -67,7 +71,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): { "type": "link", "url": repo_url, - "tooltip": "Source repository", + "tooltip": translation("Source repository"), "text": "repository", "icon": "fab fa-github", } @@ -78,8 +82,8 @@ def add_header_buttons(app, pagename, templatename, context, doctree): { "type": "link", "url": f"{repo_url}/issues/new?title=Issue%20on%20page%20%2F{context['pagename']}.html&body=Your%20issue%20content%20here.", # noqa: E501 - "text": "open issue", - "tooltip": "Open an issue", + "text": translation("open issue"), + "tooltip": translation("Open an issue"), "icon": "fas fa-lightbulb", } ) @@ -101,12 +105,13 @@ def add_header_buttons(app, pagename, templatename, context, doctree): } ) + provider, url = context["get_edit_provider_and_url"]() repo_buttons.append( { "type": "link", - "url": context["get_edit_url"](), - "tooltip": "Edit this page", - "text": "suggest edit", + "url": url, + "tooltip": translation("Edit on") + f"{provider}", + "text": translation("suggest edit"), "icon": "fas fa-pencil-alt", } ) @@ -116,7 +121,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): header_buttons.append( { "type": "group", - "tooltip": "Source repositories", + "tooltip": translation("Source repositories"), "icon": "fab fa-github", "buttons": repo_buttons, "label": "repository-buttons", @@ -139,7 +144,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "url": f'{pathto("_sources", 1)}/{context.get("ipynb_source")}', "text": ".ipynb", "icon": "fas fa-code", - "tooltip": "Download notebook file", + "tooltip": translation("Download notebook file"), } ) @@ -148,7 +153,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "type": "link", "url": f'{pathto("_sources", 1)}/{context["sourcename"]}', "text": suff, - "tooltip": "Download source file", + "tooltip": translation("Download source file"), "icon": "fas fa-file", } ) @@ -157,7 +162,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "type": "javascript", "javascript": "window.print()", "text": ".pdf", - "tooltip": "Print to PDF", + "tooltip": translation("Print to PDF"), "icon": "fas fa-file-pdf", } ) @@ -166,7 +171,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): header_buttons.append( { "type": "group", - "tooltip": "Download this page", + "tooltip": translation("Download this page"), "icon": "fas fa-download", "buttons": download_buttons, "label": "download-buttons", diff --git a/src/sphinx_book_theme/header_buttons/launch.py b/src/sphinx_book_theme/header_buttons/launch.py index 980d541a..323368ec 100644 --- a/src/sphinx_book_theme/header_buttons/launch.py +++ b/src/sphinx_book_theme/header_buttons/launch.py @@ -4,12 +4,16 @@ from docutils.nodes import document from sphinx.application import Sphinx +from sphinx.locale import get_translation from sphinx.util import logging from shutil import copy2 SPHINX_LOGGER = logging.getLogger(__name__) +MESSAGE_CATALOG_NAME = "booktheme" +translation = get_translation(MESSAGE_CATALOG_NAME) + def add_launch_buttons( app: Sphinx, @@ -112,7 +116,7 @@ def add_launch_buttons( { "type": "link", "text": "Binder", - "tooltip": "Launch on Binder", + "tooltip": translation("Launch on") + "Binder", "icon": "_static/images/logo_binder.svg", "url": url, } @@ -130,7 +134,7 @@ def add_launch_buttons( { "type": "link", "text": "JupyterHub", - "tooltip": "Launch on JupyterHub", + "tooltip": translation("Launch on") + "JupyterHub", "icon": "_static/images/logo_jupyterhub.svg", "url": url, } @@ -142,7 +146,7 @@ def add_launch_buttons( { "type": "link", "text": "Colab", - "tooltip": "Launch on Colab", + "tooltip": translation("Launch on") + "Colab", "icon": "_static/images/logo_colab.png", "url": url, } @@ -155,7 +159,7 @@ def add_launch_buttons( { "type": "link", "text": "Deepnote", - "tooltip": "Launch on Deepnote", + "tooltip": translation("Launch on") + "Deepnote", "icon": "_static/images/logo_deepnote.svg", "url": url, } @@ -166,8 +170,8 @@ def add_launch_buttons( launch_buttons_list.append( { "type": "javascript", - "text": "Live Code", - "tooltip": "Launch Thebe", + "text": translation("Live Code"), + "tooltip": translation("Launch Thebe"), "javascript": "initThebeSBT()", "icon": "fas fa-play", "label": "launch-thebe", @@ -179,7 +183,7 @@ def add_launch_buttons( header_buttons.append( { "type": "group", - "tooltip": "Launch interactive content", + "tooltip": translation("Launch interactive content"), "icon": "fas fa-rocket", "buttons": launch_buttons_list, "label": "launch-buttons", diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/article-header-buttons.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/article-header-buttons.html new file mode 100644 index 00000000..ea48bd2c --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/article-header-buttons.html @@ -0,0 +1,15 @@ +{% from "../macros/buttons.html" import render_funcs with context %} + +
    +{%- for button in header_buttons -%} +{% set btype = button.get("type") %} +{% set bopts = button.copy() %} +{% set _ = bopts.pop("type") %} +{{ render_funcs[btype](**bopts) }} +{%- endfor -%} + +{#- Extra theme buttons #} +{% include "theme-switcher.html" %} +{% include "search-button.html" %} +{% include "toggle-secondary-sidebar.html" %} +
    diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/sidebar-icons.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/sidebar-icons.html deleted file mode 100644 index e69de29b..00000000 diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-primary-sidebar.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-primary-sidebar.html new file mode 100644 index 00000000..c8139e85 --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-primary-sidebar.html @@ -0,0 +1,3 @@ + diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html new file mode 100644 index 00000000..07459f9b --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html @@ -0,0 +1,7 @@ +{# The in-page Table of Contents -#} +{% set page_toc = generate_toc_html() -%} +{% if page_toc -%} + +{%- endif %} diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/layout.html b/src/sphinx_book_theme/theme/sphinx_book_theme/layout.html index 29d9ee4d..0d56fc1f 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/layout.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/layout.html @@ -29,6 +29,3 @@

    {{ translate(theme_toc_title) }}

    {{ super() }} {% endblock %} - -{%- block footer %} -{%- endblock %} diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html b/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html index 7e9287bc..5cbc2b5d 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/macros/buttons.html @@ -14,20 +14,22 @@ {% endmacro %} -{% macro render_link_button(url, tooltip=None, icon=None, text=None, label=None, classes="") -%} +{% macro render_link_button(url, tooltip=None, tooltip_placement="bottom", icon=None, text=None, label=None, classes="") -%} {{ render_inner_html(icon, text) }} {% endmacro %} -{% macro render_js_button(javascript, tooltip=None, icon=None, text=None, label=None, classes="") %} +{% macro render_js_button(javascript, tooltip=None, tooltip_placement="bottom", icon=None, text=None, label=None, classes="") %} @@ -43,7 +45,10 @@
      {%- for button in buttons %} -
    • {{ render_funcs[button.pop("type")](classes="dropdown-item", **button) }} + {% set btype = button.get("type") %} + {% set bopts = button.copy() %} + {% set _ = bopts.pop("type") %} +
    • {{ render_funcs[btype](classes="dropdown-item", tooltip_placement="left", **bopts) }}
      • {% endfor %}
    diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/sections/header-article.html b/src/sphinx_book_theme/theme/sphinx_book_theme/sections/header-article.html deleted file mode 100644 index bc2c8ba4..00000000 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/sections/header-article.html +++ /dev/null @@ -1,22 +0,0 @@ -{# To trigger whether the TOC and its button show up #} -{% set page_toc = generate_toc_html() %} -{% from "../macros/buttons.html" import render_funcs with context %} - -
    -
    - -
    -
    - {%- for button in header_buttons -%} - {{ render_funcs[button.pop("type")](**button) }} - {%- endfor -%} - - {% if page_toc -%} - - {%- endif %} -
    -
    diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf index f822cafa..9d58e6ac 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf @@ -1,29 +1,52 @@ [theme] inherit = pydata_sphinx_theme pygments_style = tango -sidebars = navbar-logo.html, search-field.html, sbt-sidebar-nav.html +sidebars = navbar-logo.html, sbt-sidebar-nav.html stylesheet = styles/sphinx-book-theme.css [options] +# Announcement bar (empty by default) announcement = -# Removes the extra page-specific links from sidebar + +# Secondary sidebar: Removes the extra page-specific links from sidebar secondary_sidebar_items = page-toc.html -footer_content_items = author.html, copyright.html, last-updated.html, extra-footer.html +toc_title = Contents + +# Article header: The top bar that is displayed on most pages +article_header_start = toggle-primary-sidebar.html +article_header_end = article-header-buttons.html +use_download_button = True +use_fullscreen_button = True +use_issues_button = False +use_repository_button = False +# Note: We also inherit use_edit_page_button from the PyData theme + +# Configuration for GitHub / GitLab repo buttons path_to_docs = repository_url = repository_branch = launch_buttons = {} + +# Header / navbar. +# Over-ride the PST navbar components (users could provide their own if they wish) +navbar_start = +navbar_center = +navbar_end = + +# Primary sidebar behavior home_page_in_toc = False show_navbar_depth = 1 -toc_title = Contents + +# Footer at the bottom of the content extra_footer = -use_download_button = True -use_fullscreen_button = True -# Repository buttons -use_issues_button = False -use_repository_button = False +footer_content_items = author.html, copyright.html, last-updated.html, extra-footer.html + +# Footer at the bottom of the site (PST over-ride) +footer_start = +footer_end = + +# Content and directive flags use_sidenotes = False -# Note: We also inherit use_edit_page_button from the PyData theme # DEPRECATE after a few release cycles expand_toc_sections = [] diff --git a/tests/test_build.py b/tests/test_build.py index d0279687..5a09c4df 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -82,7 +82,7 @@ def test_build_book(sphinx_build_factory, file_regression): for filename, kernel in kernels_expected.items(): ntbk_html = sphinx_build.html_tree("section1", filename) thebe_config = ntbk_html.find("script", attrs={"type": "text/x-thebe-config"}) - kernel_name = 'kernelName: "{}",'.format(kernel) + kernel_name = 'name: "{}",'.format(kernel) if kernel_name not in thebe_config.prettify(): raise AssertionError(f"{kernel_name} not in {kernels_expected}") @@ -192,7 +192,7 @@ def test_header_repository_buttons( ) header = sphinx_build.html_tree("section1", "ntbk.html").select( - ".header-article__right" + ".header-article-items__end" ) file_regression.check( header[0].prettify(), @@ -225,7 +225,7 @@ def test_repo_custombranch(sphinx_build_factory, file_regression): }, ).build(assert_pass=True) header = sphinx_build.html_tree("section1", "ntbk.html").select( - ".header-article__right" + ".header-article-items__end" ) # The Binder link should point to `foo`, as should the `edit` button file_regression.check( diff --git a/tests/test_build/build__header-article.html b/tests/test_build/build__header-article.html index 78b09a70..c81dbc34 100644 --- a/tests/test_build/build__header-article.html +++ b/tests/test_build/build__header-article.html @@ -1,38 +1,44 @@
    -
    -
    - +
    +
    +
    + +
    -
    -
    - - +
    + +
    + + +
    + + +
    diff --git a/tests/test_build/build__pagetoc--page-multipletitles.html b/tests/test_build/build__pagetoc--page-multipletitles.html index 8eb96899..387806c9 100644 --- a/tests/test_build/build__pagetoc--page-multipletitles.html +++ b/tests/test_build/build__pagetoc--page-multipletitles.html @@ -1,37 +1,39 @@
    -
    -
    - - - On this page +
    +
    +
    + + + On this page +
    +
    -
    diff --git a/tests/test_build/build__pagetoc--page-onetitle.html b/tests/test_build/build__pagetoc--page-onetitle.html index 4fb8e175..13a6601e 100644 --- a/tests/test_build/build__pagetoc--page-onetitle.html +++ b/tests/test_build/build__pagetoc--page-onetitle.html @@ -1,23 +1,25 @@
    -
    -
    - - - On this page +
    +
    +
    + + + On this page +
    +
    -
    diff --git a/tests/test_build/build__pagetoc--page-onetitlenoheadings.html b/tests/test_build/build__pagetoc--page-onetitlenoheadings.html deleted file mode 100644 index dde1aee4..00000000 --- a/tests/test_build/build__pagetoc--page-onetitlenoheadings.html +++ /dev/null @@ -1,2 +0,0 @@ -
    -
    diff --git a/tests/test_build/build__sidebar-primary__nav.html b/tests/test_build/build__sidebar-primary__nav.html deleted file mode 100644 index 540a9b37..00000000 --- a/tests/test_build/build__sidebar-primary__nav.html +++ /dev/null @@ -1,90 +0,0 @@ - diff --git a/tests/test_build/header__repo-buttons--all-off.html b/tests/test_build/header__repo-buttons--all-off.html index fe4fec4e..4c2cabfd 100644 --- a/tests/test_build/header__repo-buttons--all-off.html +++ b/tests/test_build/header__repo-buttons--all-off.html @@ -1,38 +1,58 @@ -
    - -
    - +
    + + +
    + + +
    diff --git a/tests/test_build/header__repo-buttons--all-on.html b/tests/test_build/header__repo-buttons--all-on.html index a41d9476..4a0829d2 100644 --- a/tests/test_build/header__repo-buttons--all-on.html +++ b/tests/test_build/header__repo-buttons--all-on.html @@ -1,38 +1,42 @@ -
    - -
    - - +
    +
    + + +
    + + +
    diff --git a/tests/test_build/header__repo-buttons--custom-branch.html b/tests/test_build/header__repo-buttons--custom-branch.html index 25d7ac80..4dda84d7 100644 --- a/tests/test_build/header__repo-buttons--custom-branch.html +++ b/tests/test_build/header__repo-buttons--custom-branch.html @@ -1,62 +1,82 @@ -
    -
    - + +
    + + + + + + + +
    + + +
    + + +
    diff --git a/tests/test_build/header__repo-buttons--one-on.html b/tests/test_build/header__repo-buttons--one-on.html index d3963f0f..4c3e5d5b 100644 --- a/tests/test_build/header__repo-buttons--one-on.html +++ b/tests/test_build/header__repo-buttons--one-on.html @@ -1,44 +1,64 @@ -
    - - - - - - - -
    - + + + + + + +
    + + +
    + + +
    diff --git a/tests/test_build/test_header_launchbtns.html b/tests/test_build/test_header_launchbtns.html index 04347c58..45a93e8a 100644 --- a/tests/test_build/test_header_launchbtns.html +++ b/tests/test_build/test_header_launchbtns.html @@ -5,7 +5,7 @@ diff --git a/tests/test_build/test_right_sidebar_title.html b/tests/test_build/test_right_sidebar_title.html index cfb30025..d13134c9 100644 --- a/tests/test_build/test_right_sidebar_title.html +++ b/tests/test_build/test_right_sidebar_title.html @@ -1,4 +1,4 @@ -
    +
    On this page From 1a8350f2d0c0b54eec6d602ed3f21fb662fdd5b8 Mon Sep 17 00:00:00 2001 From: AakashGC Date: Mon, 20 Feb 2023 01:45:54 +1100 Subject: [PATCH 03/22] FIX: Translation support and add new translations (#684) --- .github/workflows/publish.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index a83308c7..05ce8f5e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -23,6 +23,7 @@ jobs: - name: Build package run: | + sudo apt-get install gettext python -m pip install -U pip build python -m build From a6bb8970af813ed82f28532d921a7cbeda02d30e Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sun, 19 Feb 2023 16:03:48 +0100 Subject: [PATCH 04/22] FIX: Extra bugs after the theme switch (#683) --- .gitignore | 3 ++ CHANGELOG.md | 6 ++-- docs/components/download.md | 9 +++++- docs/conf.py | 28 +++++++++++++++++-- docs/content/index.md | 1 + docs/reference/notebooks.md | 21 +++++++------- pyproject.toml | 2 +- src/sphinx_book_theme/__init__.py | 9 +++--- src/sphinx_book_theme/_transforms.py | 2 +- src/sphinx_book_theme/assets/scripts/index.js | 19 +++++++++---- .../styles/components/_primary-nav.scss | 11 -------- .../assets/styles/components/_search.scss | 21 ++++++++++++++ .../assets/styles/index.scss | 1 - .../styles/sections/_header-primary.scss | 10 ------- .../styles/sections/_sidebar-primary.scss | 5 ++++ .../styles/sections/_sidebar-secondary.scss | 5 ++++ .../header_buttons/__init__.py | 22 +++++++++++++-- .../components/page-toc.html | 15 ++++++++++ tests/test_build.py | 2 +- .../build__pagetoc--page-multipletitles.html | 2 +- .../build__pagetoc--page-onetitle.html | 2 +- .../test_build/test_right_sidebar_title.html | 2 +- 22 files changed, 141 insertions(+), 57 deletions(-) delete mode 100644 src/sphinx_book_theme/assets/styles/components/_primary-nav.scss create mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html diff --git a/.gitignore b/.gitignore index 8db3e905..6792e53d 100644 --- a/.gitignore +++ b/.gitignore @@ -138,3 +138,6 @@ node_modules/ # Editors .vscode/ .idea + +# Files we create automatically +docs/content/pydata-content-blocks.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ac3dadc..02e8b50b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -233,11 +233,11 @@ This updates to the latest PyData Sphinx Theme, which re-works some of the HTML ([full changelog](https://github.com/executablebooks/sphinx-book-theme/compare/v0.0.38...v0.0.39)) ### New features added -* sphinx sidebars functionality [#233](https://github.com/executablebooks/sphinx-book-theme/pull/233) ([@choldgraf](https://github.com/choldgraf)). You can now use the `html_sidebars` functionality that is native in Sphinx. [See the sidebars documentation](https://sphinx-book-theme.readthedocs.io/en/latest/customize/sidebar-primary.html). -* Collapsible lists in sidebars [#226](https://github.com/executablebooks/sphinx-book-theme/pull/226) ([@AakashGfude](https://github.com/AakashGfude)). Sidebars that have nested sections will now have an arrow that allows you to reveal these sections without changing the current page. You can [control the depth](https://sphinx-book-theme.readthedocs.io/en/latest/customize/sidebar-primary.html#control-the-depth-of-the-left-sidebar-lists-to-expand) of expanded sections with `show_navbar_depth`. +* sphinx sidebars functionality [#233](https://github.com/executablebooks/sphinx-book-theme/pull/233) ([@choldgraf](https://github.com/choldgraf)). You can now use the `html_sidebars` functionality that is native in Sphinx. [See the sidebars documentation](https://sphinx-book-theme.readthedocs.io/en/latest/sections/sidebar-primary.html). +* Collapsible lists in sidebars [#226](https://github.com/executablebooks/sphinx-book-theme/pull/226) ([@AakashGfude](https://github.com/AakashGfude)). Sidebars that have nested sections will now have an arrow that allows you to reveal these sections without changing the current page. You can [control the depth](https://sphinx-book-theme.readthedocs.io/en/latest/sections/sidebar-primary.html#control-the-depth-of-the-left-sidebar-lists-to-expand) of expanded sections with `show_navbar_depth`. ### Enhancements made -* Option for download button [#245](https://github.com/executablebooks/sphinx-book-theme/pull/245) ([@bknaepen](https://github.com/bknaepen)). The "download" button used to be automatically added, but can now be removed. See [the download button configuration](https://sphinx-book-theme.readthedocs.io/en/latest/customize/download.html). +* Option for download button [#245](https://github.com/executablebooks/sphinx-book-theme/pull/245) ([@bknaepen](https://github.com/bknaepen)). The "download" button used to be automatically added, but can now be removed. See [the download button configuration](https://sphinx-book-theme.readthedocs.io/en/latest/components/download.html). ## v0.0.38 diff --git a/docs/components/download.md b/docs/components/download.md index 683e6945..8c2e24e5 100644 --- a/docs/components/download.md +++ b/docs/components/download.md @@ -1,7 +1,8 @@ # Add a download page button -You can add a button allowing users to download the currently viewed page in several formats: raw, pdf or ipynb if available. To include this button, use the following configuration: +You can add a button allowing users to download the currently viewed page in several formats: `raw source`, `pdf` or `ipynb` if one was generated as part of the build. +To include this button, use the following configuration: ```python html_theme_options = { @@ -10,3 +11,9 @@ html_theme_options = { ... } ``` + +```{note} +This theme over-rides the Sphinx default for `html_source_suffix` to be `''` instead of `.txt`. +This is because most users of this theme want to download source files of the pages themselves, which do not begin with `.txt`. +If you wish to add a different source suffix, manually specify `html_source_suffix` in `conf.py`. +``` diff --git a/docs/conf.py b/docs/conf.py index 4e1247ad..4673bda5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,10 @@ # -- Project information ----------------------------------------------------- import os +from urllib.request import urlopen +from pathlib import Path project = "Sphinx Book Theme" -copyright = "2020" +copyright = "2023" author = "the Executable Book Project" # language = "fr" # For testing language translations @@ -77,7 +79,6 @@ html_logo = "_static/logo-wide.svg" html_title = "Sphinx Book Theme" html_copy_source = True -html_sourcelink_suffix = "" html_favicon = "_static/logo-square.svg" html_last_updated_fmt = "" @@ -128,7 +129,7 @@ ), "logo": { "image_dark": "_static/logo-wide-dark.svg", - } + }, # For testing # "use_fullscreen_button": False, # "home_page_in_toc": True, @@ -166,6 +167,27 @@ ] +# -- Download latest theme elements page from PyData ----------------------------- + +path_pydata_content = "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/user_guide/theme-elements.md" # noqa +path_content_file = Path(__file__).parent / "content/pydata-content-blocks.md" +if not path_content_file.exists(): + with urlopen(path_pydata_content) as resp: + # Read in the content page file, then update the title and add context + content = resp.read().decode().split("\n") + ix_title = content.index("# Theme-specific elements") + content[ix_title] = "# PyData Theme Elements" + content.insert( + ix_title + 1, + "\nThis is a collection of content blocks with special support from this theme's parent theme, [the PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/theme-elements.html)\n", # noqa + ) # noqa + content = "\n".join(content) + # Replace a relative link in the pydata docs w/ the respective one here + content = content.replace("../examples/pydata.md", "notebooks.md") + # Write to disk in a location that will be ignored by git + path_content_file.write_text(content) + + def setup(app): # -- To demonstrate ReadTheDocs switcher ------------------------------------- # This links a few JS and CSS files that mimic the environment that RTD uses diff --git a/docs/content/index.md b/docs/content/index.md index 78c5b3a3..87aae581 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -4,6 +4,7 @@ These sections describe content-specific customization and formatting. ```{toctree} content-blocks +pydata-content-blocks notebooks launch ``` diff --git a/docs/reference/notebooks.md b/docs/reference/notebooks.md index f9b011f5..ec1966b5 100644 --- a/docs/reference/notebooks.md +++ b/docs/reference/notebooks.md @@ -16,22 +16,23 @@ kernelspec: This is a page to demonstrate the look and feel of Jupyter Notebook elements. - ## Hiding elements -### Hiding inputs +### Hide cells + +The following cell is hidden. +It also has a `thebe-init` tag which means it will be executed when you initialize Thebe. ```{code-cell} ipython3 -:tags: [remove-cell] +:tags: [hide-cell, thebe-init] # Generate some code that we'll use later on in the page import numpy as np import matplotlib.pyplot as plt - -square = np.random.randn(100, 100) -wide = np.random.randn(100, 1000) ``` +### Hide inputs + ```{code-cell} ipython3 :tags: [hide-input] @@ -46,7 +47,7 @@ fig, ax = plt.subplots() ax.imshow(wide) ``` -### Hiding outputs +### Hide outputs ```{code-cell} ipython3 :tags: [hide-output] @@ -62,7 +63,7 @@ fig, ax = plt.subplots() ax.imshow(wide) ``` -### Hiding markdown +### Hide markdown ````{toggle} ```{note} @@ -79,7 +80,7 @@ With a body! +++ -### Hiding both inputs and outputs +### Hide both inputs and outputs ```{code-cell} ipython3 :tags: [hide-output, hide-input] @@ -94,7 +95,7 @@ fig, ax = plt.subplots() ax.imshow(wide) ``` -### Hiding the whole cell +### Hide the whole cell ```{code-cell} ipython3 :tags: [hide-cell] diff --git a/pyproject.toml b/pyproject.toml index 3d7bb6ed..3718da21 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ readme = "README.md" requires-python = ">=3.7" dependencies = [ "sphinx>=4,<7", - "pydata-sphinx-theme>=0.13.0rc3", + "pydata-sphinx-theme>=0.13.0rc4", ] license = { file = "LICENSE" } diff --git a/src/sphinx_book_theme/__init__.py b/src/sphinx_book_theme/__init__.py index 58854270..91fee190 100644 --- a/src/sphinx_book_theme/__init__.py +++ b/src/sphinx_book_theme/__init__.py @@ -11,7 +11,7 @@ from sphinx.util import logging from .nodes import SideNoteNode -from .header_buttons import prep_header_buttons, add_header_buttons +from .header_buttons import prep_header_buttons, add_header_buttons, update_sourcename from .header_buttons.launch import add_launch_buttons from ._transforms import HandleFootnoteTransform @@ -60,7 +60,7 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree): context["translate"] = translation # If search text hasn't been manually specified, use a shorter one here - theme_options = app.config.html_theme_options or {} + theme_options = app.builder.theme_options or {} if "search_bar_text" not in theme_options: context["theme_search_bar_text"] = translation("Search") + "..." @@ -115,7 +115,7 @@ def hash_html_assets(app, pagename, templatename, context, doctree): def update_mode_thebe_config(app): """Update thebe configuration with SBT-specific values""" - theme_options = app.env.config.html_theme_options + theme_options = app.builder.theme_options if theme_options.get("launch_buttons", {}).get("thebe") is True: # In case somebody specifies they want thebe in a launch button # but has not activated the sphinx_thebe extension. @@ -154,7 +154,7 @@ def check_deprecation_keys(app): deprecated_config_list = ["single_page"] for key in deprecated_config_list: - if key in app.env.config.html_theme_options: + if key in app.builder.theme_options: SPHINX_LOGGER.warning( f"'{key}' was deprecated from version 0.3.4 onwards. See the CHANGELOG for more information: https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md" # noqa: E501 f"[{DEFAULT_LOG_TYPE}]", @@ -226,6 +226,7 @@ def setup(app: Sphinx): # Events app.connect("builder-inited", update_mode_thebe_config) app.connect("builder-inited", check_deprecation_keys) + app.connect("builder-inited", update_sourcename) app.connect("config-inited", update_general_config) app.connect("html-page-context", add_metadata_to_page) app.connect("html-page-context", hash_html_assets) diff --git a/src/sphinx_book_theme/_transforms.py b/src/sphinx_book_theme/_transforms.py index d30c8e3d..a990d9e5 100644 --- a/src/sphinx_book_theme/_transforms.py +++ b/src/sphinx_book_theme/_transforms.py @@ -12,7 +12,7 @@ class HandleFootnoteTransform(SphinxPostTransform): formats = ("html",) def run(self, **kwargs: Any) -> None: - theme_options = self.env.config.html_theme_options + theme_options = self.app.builder.theme_options if theme_options.get("use_sidenotes", False) is False: return None # Cycle through footnote references, and move their content next to the diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index adc3e6c1..372e2639 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -160,11 +160,19 @@ var initThebeSBT = () => { */ function addNoPrint() { - document.querySelector("div.bd-sidebar-primary").classList.add("noprint"); - document.querySelector("div.bd-sidebar-secondary").classList.add("noprint"); - document.querySelector("div.bd-header-article").classList.add("noprint"); - document.querySelector("div.bd-header-announcement").classList.add("noprint"); - document.querySelector("footer.bd-footer-article").classList.add("noprint"); + var noPrintSelector = [ + ".bd-header-announcement", + ".bd-header", + ".bd-header-article", + ".bd-sidebar-primary", + ".bd-sidebar-secondary", + ".bd-footer-article", + ".bd-footer-content", + ".bd-footer", + ].join(","); + document.querySelectorAll(noPrintSelector).forEach((ii) => { + ii.classList.add("noprint"); + }); } /** @@ -178,4 +186,3 @@ window.toggleFullScreen = toggleFullScreen; */ sbRunWhenDOMLoaded(initTocHide); sbRunWhenDOMLoaded(addNoPrint); -sbRunWhenDOMLoaded(setMode); diff --git a/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss b/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss deleted file mode 100644 index 75137a72..00000000 --- a/src/sphinx_book_theme/assets/styles/components/_primary-nav.scss +++ /dev/null @@ -1,11 +0,0 @@ -/** - * Primary navigation links in the sidebar - */ - -// UPSTREAM -.bd-sidenav { - // Prevent really long words from spilling out of sidebar - li { - word-wrap: break-word; - } -} diff --git a/src/sphinx_book_theme/assets/styles/components/_search.scss b/src/sphinx_book_theme/assets/styles/components/_search.scss index 9c254493..ac344355 100644 --- a/src/sphinx_book_theme/assets/styles/components/_search.scss +++ b/src/sphinx_book_theme/assets/styles/components/_search.scss @@ -13,3 +13,24 @@ .search-button i { font-size: 1.1rem; } + +// The "clear search results" button +// Make it line up with our content better +div#searchbox { + padding-right: 2rem; + padding-left: 2rem; + @media (max-width: $breakpoint-md) { + padding-right: 1rem; + padding-left: 1rem; + } + + p.highlight-link { + // Remove the extra margin that is added + @media (min-width: $breakpoint-md) { + margin-left: 0; + a { + font-size: 1rem; + } + } + } +} diff --git a/src/sphinx_book_theme/assets/styles/index.scss b/src/sphinx_book_theme/assets/styles/index.scss index 39da0e0f..1c42f7ed 100644 --- a/src/sphinx_book_theme/assets/styles/index.scss +++ b/src/sphinx_book_theme/assets/styles/index.scss @@ -28,7 +28,6 @@ // Re-usable components across the theme @import "components/logo"; -@import "components/primary-nav"; @import "components/search"; // Content blocks in standard Sphinx diff --git a/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss index f1fc635c..f391b609 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_header-primary.scss @@ -15,14 +15,4 @@ .navbar-persistent--mobile { display: none; } - - // UPSTREAM to fix this bug - // These rules are applied too-selectively in the PST so they don't apply - // to the `navbar_start` items. This just applies the same rule to *all* items. - .navbar-item { - align-items: center; - display: flex; - height: var(--pst-header-height); - max-height: var(--pst-header-height); - } } diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss index 09b32d91..0eaa2c80 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss @@ -7,6 +7,11 @@ top: 0; max-height: 100vh; + @media (max-width: $breakpoint-md) { + // So that tooltips don't overlap + z-index: $zindex-tooltip + 1; + } + transition: margin-left $animation-time ease 0s, opacity $animation-time ease 0s, visibility $animation-time ease 0s; diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss index 7fb9013b..32841523 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss @@ -6,6 +6,11 @@ // So that it sticks to the top of the page instead of the header height top: 0; + @media (max-width: $breakpoint-lg) { + // So that tooltips don't overlap + z-index: $zindex-tooltip + 1; + } + // So that we can center the TOC button with the article header buttons .sidebar-secondary-items { padding: 0; diff --git a/src/sphinx_book_theme/header_buttons/__init__.py b/src/sphinx_book_theme/header_buttons/__init__.py index cf36d137..d1b7247e 100644 --- a/src/sphinx_book_theme/header_buttons/__init__.py +++ b/src/sphinx_book_theme/header_buttons/__init__.py @@ -22,6 +22,12 @@ def _as_bool(var): return False +def _config_provided_by_user(app, key): + """Check if the user has manually provided the config.""" + # TODO: Remove this when we bump pydata to the latest version and import from there. + return any(key in ii for ii in [app.config.overrides, app.config._raw_config]) + + def prep_header_buttons(app, pagename, templatename, context, doctree): """Prep an empty list that we'll populate with header buttons.""" context["header_buttons"] = [] @@ -29,7 +35,7 @@ def prep_header_buttons(app, pagename, templatename, context, doctree): def add_header_buttons(app, pagename, templatename, context, doctree): """Populate the context with header button metadata we'll insert in templates.""" - opts = app.config.html_theme_options + opts = app.builder.theme_options pathto = context["pathto"] header_buttons = context["header_buttons"] @@ -136,7 +142,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): if _as_bool(opts.get("use_download_button", True)) and suff: download_buttons = [] - # Create the dropdown list of buttons + # An ipynb file if it was created as part of the build (e.g. by MyST-NB) if context.get("ipynb_source"): download_buttons.append( { @@ -148,6 +154,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): } ) + # Download the source file download_buttons.append( { "type": "link", @@ -177,3 +184,14 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "label": "download-buttons", } ) + + +def update_sourcename(app): + # Download the source file + # Sphinx defaults to .txt for html_source_suffix even though the pages almost + # always are stored in their native suffix (.rst, .md, or .ipynb). So unless + # the user manually specifies an html_source_suffix, default to an empty string. + # _raw_config is the configuration as provided by the user. + # If a key isn't in it, then the user didn't provide it + if not _config_provided_by_user(app, "html_sourcelink_suffix"): + app.config.html_sourcelink_suffix = "" diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html new file mode 100644 index 00000000..e0dbff43 --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html @@ -0,0 +1,15 @@ +{# + This is a copy-paste of the PyData theme so that the title is configurable. + We over-write that component here just to monkey patch it. + We can delete it if the title is configurable in the pydata theme + Here's the ref: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html +-#} +{% set page_toc = generate_toc_html() %} +{%- if page_toc | length >= 1 %} +
    + {{ translate(theme_toc_title) }} +
    + +{%- endif %} diff --git a/tests/test_build.py b/tests/test_build.py index 5a09c4df..6023a714 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -299,7 +299,7 @@ def test_header_fullscreen_button_off(sphinx_build_factory, file_regression): def test_right_sidebar_title(sphinx_build_factory, file_regression): - confoverrides = {"html_theme_options.toc_title": "My Contents"} + confoverrides = {"html_theme_options.toc_title": "My test content title"} sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build( assert_pass=True ) diff --git a/tests/test_build/build__pagetoc--page-multipletitles.html b/tests/test_build/build__pagetoc--page-multipletitles.html index 387806c9..be65805e 100644 --- a/tests/test_build/build__pagetoc--page-multipletitles.html +++ b/tests/test_build/build__pagetoc--page-multipletitles.html @@ -4,7 +4,7 @@
    - On this page + Contents
    -
    +