Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Prototype landing page edits #557

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Prototype landing page edits #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/customize/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ The following options are available via `html_theme_options`
```{list-table}
:widths: 10 5 40
:header-rows: 1
:class: full-width

* - Key
- Type
- Description
Expand Down
3 changes: 3 additions & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
---
title: The Sphinx Book Theme
theme:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
theme:
theme_html:

(or html_theme)

this makes the purpose clearer, and would allow for e.g. the future addition of theme_latex etc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what do you think about nested?

theme:
    html:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah I just realized that this might be weird to parse in Sphinx though, since the nested levels are stringified right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess partly it depends if/how you want to have this work with RST.
For that you can only do non-nested field lists, e.g.

:name: value

so even html_theme + variable keys, won't "work", e.g. you would need to do:

:html_theme: {"key": "variable"}

For myst, yeh everything under the top-level key will be serialized to JSON, but then you would just need to deserialize, when you read it from the env.metadata[docname]["html_theme"]or env.metadata[docname]["theme"]

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My feeling is that we don't want to constrain MyST (or Jupyter Book) on what is possible with rST. I'd be OK with telling users "if you want nested metadata in the header, then your content should be MyST". Any objection to that?

I have a slight preference for:

theme:
    html:
        foo: bar
    latex:
		foo: bar

over

theme_html:
	foo: bar
theme_latex:
	foo: bar

but not a strong opinion, what do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeh, no strong preference either

collapse_sidebar: true
full_width: true
---

::::{grid}
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ doc = [
"numpy",
"matplotlib",
"numpydoc",
"myst-nb~=0.13",
"myst-nb~=0.13.2",
"nbclient",
"pandas",
"plotly",
Expand Down
29 changes: 28 additions & 1 deletion src/sphinx_book_theme/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
"""A lightweight book theme based on the pydata sphinx theme."""
import json
import hashlib
import os
from pathlib import Path
Expand Down Expand Up @@ -28,7 +29,10 @@ def get_html_theme_path():


def add_metadata_to_page(app, pagename, templatename, context, doctree):
"""Adds some metadata about the page that we re-use later."""
"""Adds some metadata about the page that we re-use later.

If page-metadata is specified, this over-rides global config.
"""
# Add the site title to our context so it can be inserted into the navbar
if not context.get("root_doc"):
# TODO: Sphinx renamed master to root in 4.x, deprecate when we drop 3.x
Expand Down Expand Up @@ -60,6 +64,29 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree):
context.get("theme_search_bar_text", "Search the docs ...")
)

# Configuration for page-level styling
page_theme_config = _get_page_theme_config(app, pagename)
theme_config_vals = [
# Collapse the sidebar if specified at the page- or site-level
"collapse_sidebar",
# Content expands to take up whole screen, TOC is hidden by default
"full_width",
]
for config_key in theme_config_vals:
config_value = context.get(f"theme_{config_key}")
config_value = page_theme_config.get(config_key, config_value)
context[config_key] = config_value


@lru_cache(maxsize=None)
def _get_page_theme_config(app, pagename):
"""Return theme config from page-level metadata."""
meta = app.env.metadata.get(pagename, {}).get("theme", {})
if meta:
# If page-level theme metadata is provided, it will be in JSON string form
meta = json.loads(meta)
return meta


@lru_cache(maxsize=None)
def _gen_hash(path: str) -> str:
Expand Down
2 changes: 1 addition & 1 deletion src/sphinx_book_theme/assets/styles/sections/_article.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ body {

#main-content,
#print-main-content {
transition: padding $animation-time ease-out;
transition: all $animation-time ease-out;
padding-top: 1.5em;
}

Expand Down
12 changes: 11 additions & 1 deletion src/sphinx_book_theme/assets/styles/sections/_sidebars-toggle.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,18 @@ input#__navigation {

// When we hide the sidebar on widescreen, add some padding to content
& ~ .container-xl #main-content {
padding-left: 4rem;
padding-left: 7rem;
padding-right: 4rem;

// At full-width, there is no margin so add some extra padding
&.full-width {
padding-left: 4rem;
padding-right: 4rem;
margin: auto;
// Set the maximum width to an L container in bootstrap
// ref: https://getbootstrap.com/docs/5.0/layout/containers/
max-width: 960px;
}
}
}
}
Expand Down
6 changes: 4 additions & 2 deletions src/sphinx_book_theme/theme/sphinx_book_theme/layout.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@

{% block content %}
<!-- Checkboxes to toggle the left sidebar -->
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle navigation sidebar">
{% set checked=" checked" if collapse_sidebar == True else "" %}
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle navigation sidebar"{{ checked }}>
<label class="overlay overlay-navbar" for="__navigation">
<div class="visually-hidden">Toggle navigation sidebar</div>
</label>
Expand Down Expand Up @@ -77,7 +78,8 @@ <h2> {{ translate(theme_toc_title) }} </h2>
</div>
</div>
</div>
<main id="main-content" role="main">
{% set full_width = ' class="full-width"' if (full_width == True) else '' %}
<main id="main-content" role="main"{{ full_width }}>
{{ super() }}
</main>
<footer class="footer-article noprint">
Expand Down
6 changes: 4 additions & 2 deletions src/sphinx_book_theme/theme/sphinx_book_theme/theme.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ repository_branch =
launch_buttons = {}
home_page_in_toc = False
logo_only =
# DEPRECATE after a few release cycles
navbar_footer_text =
show_navbar_depth = 1
collapse_sidebar = false
full_width = false
toc_title = Contents
extra_navbar = Theme by the <a href="https://ebp.jupyterbook.org">Executable Book Project</a>
extra_footer =
Expand All @@ -26,4 +26,6 @@ use_fullscreen_button = True
# Repository buttons
use_issues_button = False
use_repository_button = False
# DEPRECATE after a few release cycles
navbar_footer_text =
# Note: We also inherit use_edit_page_button from the PyData theme