Making navbar + a few other sections more modular #355

choldgraf · 2021-03-27T21:15:39Z

This is an attempt at making the navbar more modular, so that it can be more easily customized. It does a couple of things, though the end-result should look the exact same as what we have right now.

It defines two new configuration: html_theme_options: {"navbar_left": ..., "navbar_menu": ...}

Each of these are a list of templates, similar to html_sidebars, that will populate the two sections of the navbar.
Removes the configuration value to put the search in the sidebar or the navbar, since people can do this via html_theme_options: {"navbar_menu": ["search-field.html"]} now.
Splits our navbar HTML into a few components in _templates/
Adds an ethical ads template
Tries to document a bit of this, and adds a little version template for the docs so that we can see how one can extend the left navbar area.

@jorisvandenbossche what do you think about this? If you're +1 then I can add some tests.

The docs previous shouldn't look any different, but just for reference: https://pydata-sphinx-theme--355.org.readthedocs.build/en/355/user_guide/index.html

(the one difference is that there should now be a little version next to the logo)

OriolAbril · 2021-03-27T22:51:27Z

I have tested it locally and can confirm that the default look is not altered and I can use the navbar-version.html approach to add the version. Thanks!

ChaiByte · 2021-03-30T01:42:43Z

How about adding a version switcher instead of just display it in the top nav-bar? (#350 ) We can put a version.json file to control how it generates. MegEngine#1

jorisvandenbossche

Cool! Fully on board with the principles, thanks!

Removes the configuration value to put the search in the sidebar or the navbar

Do you know if there is an easy way to deprecate this first?

jorisvandenbossche · 2021-03-31T08:21:09Z

docs/conf.py

+from pathlib import Path

+for ii in Path("../pydata_sphinx_theme/__init__.py").read_text().split("\n"):
+    if ii.startswith("__version__"):
+        version = release = ii.split("= ")[-1].strip('"').replace("dev0", "")


You could also import the package and get pydata_sphinx_theme.__version__ ?

docs/user_guide/configuring.rst

jorisvandenbossche · 2021-03-31T08:26:40Z

docs/user_guide/configuring.rst

+
+   Generally speaking, navbar menu items will be **right-aligned**. However, the
+   ``navbar-menu-nav.html`` template any anything that comes before it will
+   be **left-aligned**.


I am wondering here: does this signal that we should rather split it in three? And also have a navbar_right option for the content that is right-aligned?

I was wondering the same thing, but wasn't sure if I had the right CSS magic to make it happen. Do you have a suggestion for the changes we'd need to make to do this? I agree that it'd be more sensible if there were:

navbar_left - left side of screen, left-justified

navbar_middle - aligned to content, or left side of screen, left-justified

navbar_right - right side of screen, right-justified

Hmm, right now the menu items and icons are in the same div, using a single class/alignment. So that's indeed a bit a bigger change to be able to split those.

We still need to ensure that the middle and right are together in the collapsible div, so that the mobile responsiveness is correct.

I did a quick attempt, see the commit I pushed. It seems to work the same as it does now (but didn't check if the alignment is still correct if you are using multiple custom templates)

pydata_sphinx_theme/_templates/navbar-menu-buttons.html

Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

choldgraf · 2021-03-31T13:27:28Z

Thanks for the review @jorisvandenbossche - some quick comments above. For this one:

Do you know if there is an easy way to deprecate this first?

Good point, what if we kept the flag, and for now if that flag exists it will manually update the nav configs to put the search template in the right place? And raise a dep warning?

jorisvandenbossche · 2021-04-01T18:59:21Z

Good point, what if we kept the flag, and for now if that flag exists it will manually update the nav configs to put the search template in the right place? And raise a dep warning?

That sounds good to me

choldgraf · 2021-04-02T03:43:19Z

@jorisvandenbossche ah nice - this almost gets there, but if you add extra items in addition to the menu, this happens:

any idea what's going wrong there?

EDIT: Ah I figured it out - just float lefts and rights:

choldgraf · 2021-04-02T04:30:10Z

OK I think I've addressed all comments, added a deprecation, fixed the CSS styling, and got the tests working. Anything else to take care of?

@jorisvandenbossche I didn't change the icon_links stuff because those configuration values etc are already in there, so if we wanted to change it we'd have to add a deprecation for it as well. It seems reasonable to do, but maybe out of scope of this PR?

choldgraf · 2021-04-02T17:34:49Z

@jorisvandenbossche what do you think about these two extra additions I can add to this PR:

Do the same thing for the footer as well as the page toc sections. So that instead of hard-coding them, we have a similar configuration value that provides a list of templates.
Make it possible for people to omit the .html in their configuration (e.g., navbar_right: ["icon-links", "other-template"]) via a simple script that just checks for whether an item has an extension, and if not, appends .html

Do those seem reasonable? I think this would then allow for most major parts of the page to be extended / configured in this way, rather than using feature flags for everything

jorisvandenbossche · 2021-04-02T20:58:34Z

Sounds good to me.

Just wondering, for the footer, I would think you will typically override the full footer? In which case you could also add a footer.html to your custom _templates ?

choldgraf · 2021-04-03T17:22:02Z

OK @jorisvandenbossche - I've added in a page_sidebar and a footer section as well, and spun out the documentation for adding HTML templates to each section into its own page, which you can check out here:

https://pydata-sphinx-theme--355.org.readthedocs.build/en/355/user_guide/sections.html

jorisvandenbossche

Cool, thanks a lot for the updates! Good idea for making a separate doc page about it

I added a bunch of comments. Large part of them are pedantic naming discussions, but since we let people override those based on the name, we should stick with the names once we introduce them, so a bit of bikeshedding can be useful then ;)

jorisvandenbossche · 2021-04-06T11:34:46Z

docs/conf.py

-    # "navbar_align": "right",  # For testing that the navbar items align properly
+    # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
+    # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+    # "navbar_left": ["navbar-logo", "navbar-version"],


It's maybe fine to include the version in our demo docs? (it can't harm to include I think, and then it's directly a test that part of this works in the online docs)

docs/user_guide/sections.rst

jorisvandenbossche · 2021-04-06T11:47:16Z

docs/user_guide/sections.rst

+- Left section: ``html_theme_options['navbar_left']``
+- Middle menu: ``html_theme_options['navbar_menu']``
+- Right section: ``html_theme_options['navbar_right']``


For the actual variable names, should we maybe use "start" and "end" instead of "left" and "right"? (it's eg also what bootstrap starts to use more: https://getbootstrap.com/docs/5.0/getting-started/rtl/#approach)

And maybe "navbar_center" instead of "navbar_menu"? (as you are free to put whatever element in there)

jorisvandenbossche · 2021-04-06T11:49:11Z

docs/user_guide/sections.rst

+   ...
+   "navbar_left": ["navbar-logo"],
+   "navbar_menu": ["navbar-menu-nav"],
+   "navbar_right": ["navbar-menu-buttons"]


Another naming suggestion:

Suggested change

"navbar_right": ["navbar-menu-buttons"]

"navbar_right": ["navbar-menu-icons"]

or "icon-links" instead of "icons" to be fully consistent with the theme option that populates them

docs/user_guide/sections.rst

pydata_sphinx_theme/__init__.py

jorisvandenbossche · 2021-04-06T12:03:16Z

pydata_sphinx_theme/_templates/last-updated.html

@@ -0,0 +1,3 @@
+<p class="last-updated">


The original had a if last_updated, should that be kept?

I was thinking that people could just provide this in the footer config if they wished, rather than using the Sphinx feature flag. Does that make sense?

I've added a docs section with a list of templates that can be inserted in. This isn't super descriptive, but I think should help people know what they can put in here. Does that work?

jorisvandenbossche · 2021-04-06T12:05:35Z

src/scss/_navbar.scss

+      float: left;
+    }
+
+    // Anything in navbar menu should be left-justified (e.g. links)


Suggested change

// Anything in navbar menu should be left-justified (e.g. links)

// Anything in right part of the navbar should be right-justified (e.g. icons)

choldgraf · 2021-04-09T02:39:11Z

Thanks for these comments @jorisvandenbossche - I implemented pretty much all of them (w/ one exception which I responded in-line above). Great points about naming things, I think "start" and "end" is much better. Let me know if there's anything else I should finish up (and maybe have a quick look that I didn't miss anything in the renaming)

jorisvandenbossche · 2021-04-09T11:56:53Z

Thanks for the updates! I pushed a small fix to add again a bit of padding at the bottom of the footer (which was removed by removing the padding around the <p> tag in the footer)

Making navbar modular

9acd8a1

choldgraf force-pushed the components branch from 031ddf4 to 9acd8a1 Compare March 27, 2021 21:16

choldgraf mentioned this pull request Mar 27, 2021

Show version in navbar #354

Closed

jorisvandenbossche reviewed Mar 31, 2021

View reviewed changes

choldgraf and others added 2 commits March 31, 2021 06:26

Update docs/user_guide/configuring.rst

74ab7c7

Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

Update docs/user_guide/configuring.rst

2b8b8fc

Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

jorisvandenbossche and others added 5 commits April 1, 2021 21:38

attempt to split in three

f25993d

Fixing tests and joris comments

180666b

merge commit

202d608

Updating webpack

2194f66

dev0

3ea1c15

choldgraf force-pushed the components branch from 4b85a87 to 3ea1c15 Compare April 2, 2021 04:32

More modularization

2f0a840

choldgraf added 5 commits April 3, 2021 03:06

More modularization of sections

36cc89a

merge master

c2dd6ff

Updating webpack

ef2d8cf

rename sidebar

e5cad21

update sidebar docs

8b6857e

jorisvandenbossche mentioned this pull request Apr 6, 2021

use official pydata sphinx theme bokeh/bokeh#10971

Merged

2 tasks

jorisvandenbossche reviewed Apr 6, 2021

View reviewed changes

Updating naming per suggestions

aad1fff

choldgraf added 3 commits April 7, 2021 00:36

more touch-ups

0a2e55a

merge commit

19f203e

list of templates

814abb3

choldgraf mentioned this pull request Apr 9, 2021

Updating to PyData Sphinx Theme open-contracting/standard#1254

Draft

7 tasks

choldgraf changed the title ~~Making navbar modular~~ Making navbar + a few other sections more modular Apr 9, 2021

jorisvandenbossche added 2 commits April 9, 2021 13:01

fix padding footer

199fa38

fix template name in docs

309a5fc

jorisvandenbossche approved these changes Apr 9, 2021

View reviewed changes

jorisvandenbossche merged commit f1e4d91 into pydata:master Apr 9, 2021

jorisvandenbossche mentioned this pull request Apr 9, 2021

✨ ENH: Support version and locale switcher #360

Closed

4 tasks

choldgraf mentioned this pull request Apr 12, 2021

the theme does not provide placement for the ethical ads of readthedoc #345

Closed

drammock mentioned this pull request Apr 13, 2021

strange navbar element ordering #383

Closed

jpmckinney mentioned this pull request May 7, 2021

Add a div for readthedocs ethical ads #69

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Making navbar + a few other sections more modular #355

Making navbar + a few other sections more modular #355

choldgraf commented Mar 27, 2021 •

edited

Loading

OriolAbril commented Mar 27, 2021

ChaiByte commented Mar 30, 2021

jorisvandenbossche left a comment

jorisvandenbossche Mar 31, 2021

jorisvandenbossche Mar 31, 2021

choldgraf Mar 31, 2021

jorisvandenbossche Apr 1, 2021

jorisvandenbossche Apr 1, 2021

choldgraf commented Mar 31, 2021 •

edited

Loading

jorisvandenbossche commented Apr 1, 2021

choldgraf commented Apr 2, 2021 •

edited

Loading

choldgraf commented Apr 2, 2021

choldgraf commented Apr 2, 2021 •

edited

Loading

jorisvandenbossche commented Apr 2, 2021

choldgraf commented Apr 3, 2021 •

edited

Loading

jorisvandenbossche left a comment

jorisvandenbossche Apr 6, 2021

jorisvandenbossche Apr 6, 2021

jorisvandenbossche Apr 6, 2021

jorisvandenbossche Apr 6, 2021

jorisvandenbossche Apr 6, 2021

choldgraf Apr 9, 2021 •

edited

Loading

jorisvandenbossche Apr 6, 2021

choldgraf commented Apr 9, 2021

jorisvandenbossche commented Apr 9, 2021 •

edited

Loading

	"navbar_right": ["navbar-menu-buttons"]
	"navbar_right": ["navbar-menu-icons"]

	// Anything in navbar menu should be left-justified (e.g. links)
	// Anything in right part of the navbar should be right-justified (e.g. icons)

Making navbar + a few other sections more modular #355

Making navbar + a few other sections more modular #355

Conversation

choldgraf commented Mar 27, 2021 • edited Loading

OriolAbril commented Mar 27, 2021

ChaiByte commented Mar 30, 2021

jorisvandenbossche 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

choldgraf commented Mar 31, 2021 • edited Loading

jorisvandenbossche commented Apr 1, 2021

choldgraf commented Apr 2, 2021 • edited Loading

choldgraf commented Apr 2, 2021

choldgraf commented Apr 2, 2021 • edited Loading

jorisvandenbossche commented Apr 2, 2021

choldgraf commented Apr 3, 2021 • edited Loading

jorisvandenbossche 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

choldgraf Apr 9, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Apr 9, 2021

jorisvandenbossche commented Apr 9, 2021 • edited Loading

choldgraf commented Mar 27, 2021 •

edited

Loading

choldgraf commented Mar 31, 2021 •

edited

Loading

choldgraf commented Apr 2, 2021 •

edited

Loading

choldgraf commented Apr 2, 2021 •

edited

Loading

choldgraf commented Apr 3, 2021 •

edited

Loading

choldgraf Apr 9, 2021 •

edited

Loading

jorisvandenbossche commented Apr 9, 2021 •

edited

Loading