Standardize template structure in more sections #1184

choldgraf · 2023-02-15T11:23:29Z

This takes another pass at our HTML section structure and (I think) standardizes it across all of our major sections. So there is now a start and end component in each of the major sections (header, primary sidebar, article header, footer). And they all have the same general inner structure. In the process I also:

Fixed the CSS for our article header so that if it is empty, it doesn't take up any vertical space.
Added a start and end to our footer, and added icon-links.html to our footer_end as well. This deprecates footer_items with a warning.
Made a few CSS tweaks to generalize the icon-links behavior to work in both the header and footer, and to not use id
Fixed a CSS selector bug in our version dropdown that should make it now work again.
Updated our layout page to reflect our most recent changes

Other than the new footer options, the visual style and layout shouldn't be changed at all

closes Standardize HTML structure and configuration of each of our major areas #1182

choldgraf · 2023-02-15T11:53:34Z

cc @drammock and @12rambau - this one is more complex than I was hoping to get into the RC, but I think it's good to standardize all this stuff at once as much as possible rather than changing the HTML layout in lots of different releases (since it's sort-of a breaking change). Let me know what you think

drammock

Various comments/questions below.

I'm also in favor of doing these big restructurings all within one release. Which to me means this should not go in the day before/day of release. It's easy to miss something with large changesets, so I prefer giving it a few days for folks to notice any regressions / missed changes and report/fix them.

Failing that (i.e., if we do merge this then release soon) I think someone should commit to being on the hook for a follow-up PR and patch release within 1 week, just in case. I'm moving house next week so I can't be that person.

docs/user_guide/layout.rst

drammock · 2023-02-15T16:24:59Z

docs/conf.py

@@ -133,12 +133,13 @@
    "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
    "navbar_center": ["version-switcher", "navbar-nav"],
    "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
+    "footer_end": ["navbar-icon-links.html"],


-0.5 on this change; on large screens our navbar is persistent / still visible when scrolling to the end so now there are 2 copies of these icon links on screen at the same time. If the point is to demo start/end positioning, we could put copyright in start and "built with..." items in end?

Ooh good idea

docs/conf.py

drammock · 2023-02-15T16:30:52Z

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -305,7 +305,7 @@ function checkPageExistsAndRedirect(event) {
 }

 // Populate the version switcher from the JSON config file
-var themeSwitchBtns = document.querySelectorAll("version-switcher__button");
+var themeSwitchBtns = document.querySelectorAll(".version-switcher__button");


this change looks unrelated, is it fixing something else?

It un breaks the version switcher i think. I noticed it while doing the work here

version switcher AJAX not working on RTD #844

Version switcher not working for old docs #932

Coloring the version switcher button does not work as expected #1128

?

I'm not sure, I just noticed that in our latest/ docs it is broken:

https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html

and this seemed like the obvious thing that was wrong

drammock · 2023-02-15T16:37:45Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html

 <div class="bd-header__inner bd-page-width">
  <label class="sidebar-toggle primary-toggle" for="__primary">
    <span class="fa-solid fa-bars"></span>
  </label>
-  <div id="navbar-start">
+  {% if theme_navbar_start %}
+  <div id="navbar-start" class="navbar-header-items__start">


why does this one get an id but many of the other start/end divs don't?

So i found there was inconsistent behavior. In some cases we used id and in others we used a class that was more specific. I think in general it's good to use classes instead of id. Want me to change that?

I'm happy to use classes unless there's something we must enforce to be unique (version switcher and search box are the only things coming to mind). So yeah, I'd keep the others as class-only and change this one to eliminate the id

drammock · 2023-02-15T16:38:20Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/sidebar-primary.html

      {%- endfor %}
    </div>
  {% endif %}
  {# Items that will snap to the bottom of the screen #}
-  <div class="sidebar-end-items sidebar-primary__section">
+  <div class="sidebar-primary-items__end sidebar-primary__section">


e.g., here's one that doesn't get an id

Co-authored-by: Daniel McCloy <dan@mccloy.info>

choldgraf · 2023-02-15T16:59:17Z

Yeah I think would warrant an rc3. I can address your comments 👍

choldgraf · 2023-02-15T20:47:10Z

OK I took a pass through the templates and tried to remove the use of id= wherever I could. There were a few spots where I think we intentionally wanted to keep it (e.g. for the skip-content link) so I left those in. I also updated all of the tests. I didn't see any obvious regressions in the docs preview and there didn't seem to be any errors in the JS (and the version dropdown seems to be working again)

If somebody merges, I'm happy to cut a new release candidate and hold off on a full release until the end of the week or next

MaurycyWojda · 2023-02-21T10:31:00Z

Hello, would it be possible to extend this functionality to add element to the article footer?
I wanted to add an HTML element to appear before the prev/next buttons, but as far as I can see this is not supported.

choldgraf · 2023-02-21T10:54:02Z

That makes sense to me - happy to review a PR that follows a similar pattern to what we did here. It'll be a while before I'm at a computer so probably can't do it myself though

* Fix extra whitespace in sidebars (pydata#1115) * Fix extra whitespace in sidebars * Searchbox * Update src/pydata_sphinx_theme/__init__.py Co-authored-by: Daniel McCloy <dan@mccloy.info> * make test pass * Fix template filter to remove empty files * ABlog in template test * Move clear search button to primary sidebar * Move search clear button to top of article Co-authored-by: Daniel McCloy <dan@mccloy.info> * FIX: Use logo_url instead deprecated logo in theme (pydata#1094) (pydata#1097) resolves pydata#1094 * ENH/MAINT: avoid overwriting the HtmlTranslator (pydata#1105) Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> Fix pydata#143 Fix pydata#94 * fix: align sidebar sliding with the buttons (pydata#1123) * fix: aline the sidebar sliding with the buttons * build: force test to run on all platform if one platform is failing we cannot see if it's platform related as the other were closed * fix: use correct path for documentation logo * MAINT: Improve font sizing (pydata#1129) Fix pydata#1001 * MAINT: Refactor workflows to reduce test dependencies (pydata#1136) * MAINT: update prerelease workflow (pydata#1140) * ABlog: Updates for new HTML structure (pydata#1118) * ABlog: Updates for new HTML structure * Update templates for latest release * Bump to dev0 * Standardize logo image behavior between Sphinx and this theme (pydata#1132) Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu> * 0.13.0rc1 * Build(deps): Bump http-cache-semantics from 4.1.0 to 4.1.1 (pydata#1154) * DOC: Use only shield.io for badges in README (pydata#1152) * Copyright semicolon (pydata#1160) * FIX: Flex behavior should shrink header items instead of brand (pydata#1158) Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> Fixes pydata#1143 * STYLE: lint the documentation with Doc8 (pydata#1150) Fix pydata#1139 * Add test for internationalization and translations (pydata#1138) * FIX: Javascript incorrect check for variable (pydata#1166) * MAINT: update pypi classifiers (pydata#1153) Fix pydata#1106 * remove emoji from landing page (pydata#1151) * add fa icons instead of emoji * remove fix for emojis * use markup for readme emojis * use pst-color-primary instead of sd-text-primary * make our semantic colors available as classes * try again --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * FIX: Narrow scope of style rule for GitHub & GitLab link shortening (pydata#1167) Fixes pydata#1156 * ENH: Add breadcrumbs to article header (pydata#1142) * ENH: Add breadcrumbs to article header * Update src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html Co-authored-by: Tania Allard <taniar.allard@gmail.com> * More fixes * Improving nested page behavior * Documenting breadcrumbs * Update src/pydata_sphinx_theme/assets/styles/components/_breadcrumbs.scss Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * Breacrumbs have link color --------- Co-authored-by: Tania Allard <taniar.allard@gmail.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * Degrade gracefully when JavaScript is disabled (pydata#1146) * Fix header vertical spacing and jupyter-sphinx cells (pydata#1164) Fixes undefined * RLS: v0.13.0rc2 (pydata#1170) * DOCS: admonition customization (pydata#1155) * first draft of the admonition customization * typo in doc link * flesh out admon. customization example; DRY * use :code:rst instead of :literal: * Update docs/_static/custom.css --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Fix article header CSS (pydata#1171) * “Edit this page” → “Edit on GitHub/GitLab/Bitbucket” (pydata#1177) * “Edit this page” → “Edit on GitHub/GitLab/Bitbucket” Fixes pydata#1172 * Add tests * Fix typo * Properly handle default_mode=auto when writing logos (pydata#1183) We used to only defaulting to the light version when `default_mode` was undefined, not when it was explicitly set to `auto`. We also need to handle the latter, as the new test shows. Closes pydata#1180 Co-authored-by: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org> * fix: correctly add DOM listeners (pydata#1179) fix adding DOM listeners * maint: update GitLab URL tests (pydata#1186) Co-authored-by: JoerivanEngelen <joerivanengelen@hotmail.com> * Standardize template structure in more sections (pydata#1184) * Standardize template structure in all sections * Fixing footer behavior * Update docs/user_guide/layout.rst Co-authored-by: Daniel McCloy <dan@mccloy.info> * Remove use of id= as much as possible --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * maint: remove sphinx-panels support; remove deprecated config shims (pydata#1188) * Minor style improvements to ablog (pydata#1185) * RLS: v0.13.0rc3 * dev0 * FIX: Some style bugs (pydata#1191) * FIX: Some style bugs * Move link word wrap to global rule * DOCS: Add internationalization instructions (pydata#1178) Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com> * Refactor contributing docs to be more modular (pydata#1173) * Dev0 * Fix github gitlab brand (pydata#1194) * RLS: v0.13.0rc4 * FIX: Make wide equations scroll (pydata#1196) * Fix math scrollbars for realz (pydata#1198) * Fix math scrollbars for realz * Update src/pydata_sphinx_theme/assets/styles/content/_math.scss * Update src/pydata_sphinx_theme/assets/styles/content/_math.scss * copy_logo_images: do not render dynamic Sphinx template content (pydata#1204) * copy_logo_images: do not render dynamic Sphinx template content when copying logo image files * Update src/pydata_sphinx_theme/__init__.py --------- Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> * Add conditional check for last-updated template (pydata#1201) * Add conditional check for last-updated template * Whitespace * Properly set configuration with app.builder.theme_options (pydata#1199) * Properly set configuration * Dict to values * Making it explicit in a function * Better name * Fix test * Foot * Revert complex config set * Clarify docs * Use CSS transform for skip link (pydata#1206) * feat: Add full i18n support (pydata#1192) Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com> Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu> Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> * Dev0 * FIX: Remove icon links component when no icon links given (pydata#1209) * RLS: 0.13.0rc5 * dev0 * FIX: Get theme options in a more robust way (pydata#1214) * RLS: v0.13.0rc6 * Make heading-style use the font-weight-heading value (pydata#1213) * Make heading-style use the font-weight-heading value * Separate font-weight setting for content headers and admonitions * Flip var to be consistent with --pst-font-weight-heading instead * RLS: v0.13.0 * bump: dev0 * DOCS: Remove <p> from announcement sample text (pydata#1223) --------- Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Nico Albers <nico.albers@aboutyou.com> Co-authored-by: Chris Holdgraf <choldgraf@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Brendan Heberlein <bheberlein@wisc.edu> Co-authored-by: Tania Allard <taniar.allard@gmail.com> Co-authored-by: Lunar <lunar@debian.org> Co-authored-by: Jean Abou-Samra <jean@abou-samra.fr> Co-authored-by: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org> Co-authored-by: JoerivanEngelen <joerivanengelen@hotmail.com> Co-authored-by: James McKinney <26463+jpmckinney@users.noreply.github.com> Co-authored-by: James Addison <55152140+jayaddison@users.noreply.github.com> Co-authored-by: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com>

michaelweinold · 2023-04-05T09:53:28Z

@choldgraf & @MaurycyWojda: Would this

I wanted to add an HTML element to appear before the prev/next buttons, but as far as I can see this is not supported.

need a new issue? From what I can see, there is no option to add an html element to the footer as of yet (like is already available for the announcement banner).

12rambau · 2023-04-05T10:10:50Z

@michaelweinold yes please, and I think depending on the problem you describe it is already possible.

MaurycyWojda · 2023-04-05T10:20:21Z

@michaelweinold & @12rambau It is already possible in the stable version, it seems.
When I commented I was looking at this. Now it looks different accoriding to what Michael linked.

But I haven't tested it. I am basing this comment on my current understanding of the docs.

michaelweinold · 2023-04-05T11:31:47Z

I would like to add an html string of this sort:

<p>Sample footer text <a href='https://example.com'></p>

between the "footer_start": ["copyright"] and the footer_end (which is not explicitly defined in the config, but displays the "Built with the PyData Sphinx Theme 0.13.3.".

I tried to add this to a footer.html file that I put into a _templates directory, as described here - that does not seem to work.

12rambau · 2023-04-05T11:40:59Z

as requested in my earlier message could we please discuss this matter in a new issue instead of a merged PR ?

choldgraf added 2 commits February 15, 2023 12:20

Standardize template structure in all sections

59401a6

Fixing footer behavior

0d6a3b2

choldgraf changed the title ~~Standardize template structure in all sections~~ Standardize template structure in more sections Feb 15, 2023

drammock reviewed Feb 15, 2023

View reviewed changes

Update docs/user_guide/layout.rst

1b5d037

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Remove use of id= as much as possible

482a317

drammock approved these changes Feb 15, 2023

View reviewed changes

drammock merged commit def7c72 into pydata:main Feb 15, 2023

12rambau mentioned this pull request Feb 16, 2023

Configurable footer components #42

Closed

datapythonista mentioned this pull request Feb 21, 2023

DOC: Simplify pandas theme footer pandas-dev/pandas#51536

Open

brichet mentioned this pull request Feb 28, 2023

Fixes documentation build jupyterlab/jupyterlab#14104

Merged

michaelweinold mentioned this pull request Apr 5, 2023

Add Footer with "open an issue on GitHub" or similar brightway-lca/brightway-documentation#73

Closed

3 tasks

michaelweinold mentioned this pull request Apr 5, 2023

Add html line to footer #1284

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Standardize template structure in more sections #1184

Standardize template structure in more sections #1184

choldgraf commented Feb 15, 2023 •

edited

Loading

choldgraf commented Feb 15, 2023

drammock left a comment

drammock Feb 15, 2023

choldgraf Feb 15, 2023

drammock Feb 15, 2023

choldgraf Feb 15, 2023

drammock Feb 15, 2023

choldgraf Feb 15, 2023

drammock Feb 15, 2023

choldgraf Feb 15, 2023

drammock Feb 15, 2023

drammock Feb 15, 2023

choldgraf commented Feb 15, 2023

choldgraf commented Feb 15, 2023 •

edited

Loading

MaurycyWojda commented Feb 21, 2023

choldgraf commented Feb 21, 2023

michaelweinold commented Apr 5, 2023

12rambau commented Apr 5, 2023 •

edited

Loading

MaurycyWojda commented Apr 5, 2023

michaelweinold commented Apr 5, 2023 •

edited

Loading

12rambau commented Apr 5, 2023

Standardize template structure in more sections #1184

Standardize template structure in more sections #1184

Conversation

choldgraf commented Feb 15, 2023 • edited Loading

choldgraf commented Feb 15, 2023

drammock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Feb 15, 2023

choldgraf commented Feb 15, 2023 • edited Loading

MaurycyWojda commented Feb 21, 2023

choldgraf commented Feb 21, 2023

michaelweinold commented Apr 5, 2023

12rambau commented Apr 5, 2023 • edited Loading

MaurycyWojda commented Apr 5, 2023

michaelweinold commented Apr 5, 2023 • edited Loading

12rambau commented Apr 5, 2023

choldgraf commented Feb 15, 2023 •

edited

Loading

choldgraf commented Feb 15, 2023 •

edited

Loading

12rambau commented Apr 5, 2023 •

edited

Loading

michaelweinold commented Apr 5, 2023 •

edited

Loading