Sidenav in mobile with toggle.

CaselIT commented 3 years ago

add bootstrap and enable the sidinav using a toggle on mobile

still to-do before this is mergiable;

[ ] check if we can add bootstrap as the first style sheet
[ ] undo most style changes done by bootstrap
[ ] disable this behavior in the index (or where there is no side sidenav)
[ ] remove the top margin on the sidenav
[ ] check if we can import only this part of bootstrap

zzzeek commented 3 years ago

tell me about bootstrap and what it's used for.

CaselIT commented 3 years ago

we are using the offcanvas of bootstrap to make the sidenav toggle

https://getbootstrap.com/docs/5.0/components/offcanvas/

zzzeek commented 3 years ago

I figured that. why not jquery? which we already use. it's very simple.

CaselIT commented 3 years ago

does jquery have a way of doing this? I don't really use it

MaicoTimmerman commented 3 years ago

Also, jQuery is almost regarded as obsolete most cases. Most of these things can be achieved using plain Javascript and CSS. Perhaps with support of bootstap-like CSS frameworks.

For reference, see http://youmightnotneedjquery.com/

zzzeek commented 3 years ago

does jquery have a way of doing this? I don't really use it

if the thing being done here is "make an element show and hide and/or change its css classes based on a button", then yes, our docs use jquery for this extensively. so this should be altered to use our existing dependencies.

zzzeek commented 3 years ago

Also, jQuery is almost regarded as obsolete most cases. Most of these things can be achieved using plain Javascript and CSS. Perhaps with support of bootstap-like CSS frameworks.

It's news to me that jquery is "obsolete", it's typically not enough for what today's heavyweight sites need, but our site is not like that, we just have a few effects here and there and additionally sphinx remains dependent on it in any case.

For reference, see http://youmightnotneedjquery.com/

i didnt find this site very convincing as it illustrated simple one line jquery calls compared to 10 or 15 lines of raw code, and it also glossed over (entirely omitted) jquery's ability to target DOM elements based on CSS classes which is the main thing that makes it very useful. im sure other frameworks do it too, great, if the proposal is to replace jquery entirely with X, that's a different issue. IIUC we have a jquery dependency for sphinx search regardless.

CaselIT commented 3 years ago

jquery's ability to target DOM elements based on CSS classes

For this you can mostly use querySelector, but I agree that jQuery has some useful shorthand. We don't have much js code, so it should be easy to change if we need to

Regarding this, I thought about using bootstrap since its a battle tested implementation that will most likely work in most cases.

I can look into trying this with jQuery to see if there's some easy solution that mostly works

zzzeek commented 3 years ago

next thing. I'm pretty sure we merged 2e8d0b51ec0e0ddcf9 to already solve the problem of sidebar on mobile. it doesn't work?

zzzeek commented 3 years ago

re: bootstrap, it looks like it's "The most popular HTML, CSS, and JS library in the world", so OK it's all three.

Basically I don't like pulling in a huge library for one small little thing, I'd rather have the whole SQLAlchemy site etc. redone on a "bootstrap" basis, where we don't use jquery at all, and the CSS and all that can integrate. then it's worthwhile bringing in what appears to be a heavyweight library here.

For mobile, I think the site does have to be re-done, because as mentioned previously I can't get even code examples to show up on a phone right now, the rules for mobile seem to be completely at odds with normal web dev (e.g. font sizes etc. are randomly obeyed/disobeyed based on some unseen heuristic).

cc @bourke for comments re: "do we need bootstrap" ?

CaselIT commented 3 years ago

next thing. I'm pretty sure we merged 2e8d0b5 to already solve the problem of sidebar on mobile. it doesn't work?

the issue is that this commit removed the sidebar also on this page https://docs.sqlalchemy.org/en/14/, preventing search completely . #7 makes it keep the sidenav on that page, and removes it on the other ones

CaselIT commented 3 years ago

I'd rather have the whole SQLAlchemy site etc. redone on a "bootstrap" basis, where we don't use jquery at all, and the CSS and all that can integrate.

do you have a template of documentation website to use as an example?

zzzeek commented 3 years ago

I'd rather have the whole SQLAlchemy site etc. redone on a "bootstrap" basis, where we don't use jquery at all, and the CSS and all that can integrate.

do you have a template of documentation website to use as an example?

for whatever reason i often use https://dev.mysql.com/doc/refman/8.0/en/ for ideas

jvanasco commented 3 years ago

tell me about bootstrap and what it's used for.

Let me try a better answer.

Bootstrap is, first and foremost, a HTML/CSS framework. There are some bells and whistles that use javascript; versions <=4.x are built on top of jquery (the "slim" build is default, but it's compatible with full); version 5.x does not require jquery but will register it's plugins into jquery if detected.

The big benefits of Bootstrap:

CSS Grid. For the past n years, the standard for building HTML websites is to use a CSS grid. For those of us who started with HTML before CSS or grids, a CSS grid basically divides a page into equal sized columns with margins.
Cross-Platform. The bootstrap library is designed and tested to maintain the grid - and helpers - across platforms.
Cross-Device/Screen-Size. The library streamlines using CSS rules for screen size, so you can better tweak how things display on mobile vs desktop. You can even use CSS rules to show two completely different experiences based on screensize.

IMHO, the ideal upgrade path would be to redeploy the docs as-is onto bootstrap, which should resolve 90% of the mobile/device issues. We can then tweak the templates and integration so mobile/device have an experience equal to desktop.

zzzeek commented 3 years ago

tell me about bootstrap and what it's used for.

Let me try a better answer.

Bootstrap is, first and foremost, a HTML/CSS framework. There are some bells and whistles that use javascript; versions <=4.x are built on top of jquery (the "slim" build is default, but it's compatible with full); version 5.x does not require jquery but will register it's plugins into jquery if detected.

OK that's great, because then it doesnt replace our jquery dependency. super helpful.

The big benefits of Bootstrap:

* CSS Grid.  For the past _n_ years, the standard for building HTML websites is to use a CSS grid.  For those of us who started with HTML before CSS or grids, a CSS grid basically divides a page into equal sized columns with margins.

yes I figured this part. I think the site / docs should try to be on a grid, which is like a rewrite. might be too much to ask, because it was really hard to get the site/docs to do all the things it does today (dropdowns, independently scrolling nav).

* Cross-Platform. The bootstrap library is designed and tested to maintain the grid - and helpers - across platforms.

* Cross-Device/Screen-Size. The library streamlines using CSS rules for screen size, so you can better tweak how things display on mobile vs desktop. You can even use CSS rules to show two completely different experiences based on screensize.

I think we have to do this. but it needs to be fully designed.

IMHO, the ideal upgrade path would be to redeploy the docs as-is onto bootstrap, which should resolve 90% of the mobile/device issues.

"as is" seems a little unlikely. how is it going to reformat our existing <pre> sections to be legible on mobile, unless it's going to rewrite all our fonts etc. ?

We can then tweak the templates and integration so mobile/device have an experience equal to desktop.

jvanasco commented 3 years ago

how is it going to reformat our existing
 sections to be legible on mobile, unless it's going to rewrite all our fonts etc. ?

code/pre blocks are natively supported (https://getbootstrap.com/docs/4.0/content/code/)

so it should work correctly out-of-the-box; then we could reintegrate your css choices for fonts/etc.

zzzeek commented 3 years ago

how is it going to reformat our existing sections to be legible on mobile, unless it's going to rewrite all our fonts etc. ?

code/pre blocks are natively supported (https://getbootstrap.com/docs/4.0/content/code/)

so it should work correctly out-of-the-box; then we could reintegrate your css choices for fonts/etc.

sure, it has CSS for pre/code, that's great, it's going to override all our existing styles? is this like, "don't use our CSS, use bootstraps' built in CSS on mobile" ? otherwise i dont see how this would work out as far as we have our own styles that don't work on mobile.

jvanasco commented 3 years ago

oh. well, i would do the migration by disabling our CSS at first, then auditing our css and deciding what to migrate and what to ignore.

zzzeek commented 3 years ago

oh. well, i would do the migration by disabling our CSS at first, then auditing our css and deciding what to migrate and what to ignore.

that's fine but it's going to be very hard, for a variety of reasons. the css is complex and the site build is hard to set up locally as well (not sure if I've shown you how to do it before).

zzzeek commented 3 years ago

next thing. I'm pretty sure we merged 2e8d0b5 to already solve the problem of sidebar on mobile. it doesn't work?

the issue is that this commit removed the sidebar also on this page https://docs.sqlalchemy.org/en/14/, preventing search completely . #7 makes it keep the sidenav on that page, and removes it on the other ones

maybe we should just hvae a differnet search UI on mobile, I dont know id want to "show nav" first to seach

CaselIT commented 2 years ago

no longer needed

sqlalchemyorg / zzzeeksphinx

Sidenav in mobile with toggle. #8