Docs: Add light-theme and use users preferred theme #268

lessp · 2023-04-26T15:29:11Z

I wasn't able to build the complete documentation, but manually checked what I could.

(disclaimer, I fed the CSS to ChatGPT and asked it to extract all the colors into a theme, I then asked it to generate a light theme based on the dark theme colors. From what I could see, the theme looks nice, IMO, of course.)

Screen.Recording.2023-04-26.at.16.44.55.mov

Would close: #235

docs/web/site/docs.css

aantron · 2023-04-26T17:26:56Z

Amazing! It seems fitting to review it on stream tomorrow, then! Thank you!

Also removed the shadow on the <h1> element. It was probably left over from an early version of the dark theme, before Dream's alpha 1 release.

lessp · 2023-04-27T17:06:09Z

Success 🎉

❯ make docs            
make -C docs/web --no-print-directory
dune build @doc --root ../.. --no-print-directory --build-dir `pwd`/odoc \
	 --only-packages dream-pure,dream-httpaf,dream
rm -f site/index.html                  
dune exec -- postprocess/index.exe \
	 odoc/default/_doc/_html/dream/Dream/index.html site/index.html
Entering directory '/Users/ekander/dev/oss/dream'
Done: 100% (2/2, 0 left) (jobs: 0)rm -f site/status/index.html
soupault
Done: 0% (0/0, 0 left) (jobs: 0)[INFO] Running with build profiles: 
[INFO] Build directory "build" does not exist, creating
[INFO] Processing page site/index.html
[INFO] Using template "index" for page site/index.html
[INFO] Processing widget relative_links on page site/index.html
[INFO] Writing generated page to build/index.html
See docs/web/build/index.html

✅ `soupault` not found

Solved by running opam install soupault

❯ make docs
make -C docs/web --no-print-directory
dune build @doc --root ../.. --no-print-directory --build-dir `pwd`/odoc \
	 --only-packages dream-pure,dream-httpaf,dream
rm -f site/index.html                  
dune exec -- postprocess/index.exe \
	 odoc/default/_doc/_html/dream/Dream/index.html site/index.html
Entering directory '/Users/ekander/dev/oss/dream'
Done: 50% (6/12, 6 left) (jobs: 0)rm -f site/status/index.html
soupault
Error: Program "soupault" not found! <-- Error is here
make[1]: *** [build] Error 1
make: *** [docs] Error 2

✅ odoc version mismatch

EDIT 3: I think I'm close, but it fails with an exception from an assertion in docs/web/postprocess/index.ml (common.ml):

Solved by running opam install odoc.2.0.2

❯ make docs
make -C docs/web --no-print-directory
dune build @doc --root ../.. --no-print-directory --build-dir `pwd`/odoc \
	 --only-packages dream-pure,dream-httpaf,dream
rm -f site/index.html                  
dune exec -- postprocess/index.exe \
	 odoc/default/_doc/_html/dream/Dream/index.html site/index.html
Entering directory '/Users/ekander/dev/oss/dream'
Done: 50% (6/12, 6 left) (jobs: 0)Fatal error: exception Failure("Mismatch; wrote /Users/ekander/dev/oss/dream/docs/web/actual")
make[1]: *** [build] Error 2
make: *** [docs] Error 2

✅ Opam Switch + Sub-modules

EDIT 2: I then ran into the following issue upon running make deps in docs/web.

[ERROR] Package conflict!
  * No agreement on the version of ocaml-base-compiler:
    - (invariant) → ocaml-base-compiler = 4.14.0
    - web → ocaml-base-compiler = 4.14.1
    You can temporarily relax the switch invariant with
      `--update-invariant'

Which I found a bit confusing, because when running opam switch I should(?) be on 4.14.1:

[NOTE] Current switch has been selected based on the current
       directory.
       The current global system switch is 4.14.1.

And so I followed the alternative instruction which seems to have done the trick:

❯ opam install --deps-only . --locked --update-invariant

Lastly(?), I then hit the following error which I have not yet resolved
✅ EDIT: Resolved by pulling the sub-modules again recursively.

❯ make docs
make -C docs/web --no-print-directory
dune build @doc --root ../.. --no-print-directory --build-dir `pwd`/odoc \
	 --only-packages dream-pure,dream-httpaf,dream
File "src/vendor/gluten/lwt-unix/_unknown_", line 1, characters 0-0:
Error: No rule found for src/vendor/gluten/lwt-unix/ssl_io.real.ml
File "src/vendor/gluten/lwt-unix/_unknown_", line 1, characters 0-0:
Error: No rule found for src/vendor/gluten/lwt-unix/tls_io.dummy.ml
File "src/vendor/httpaf/lib/httpaf.mli", line 46, characters 0-11:
46 | open Result
     ^^^^^^^^^^^
Error (warning 33 [unused-open]): unused open Stdlib.Result.
File "src/vendor/gluten/lwt/gluten_lwt_intf.ml", line 63, characters 19-33:
63 |     -> protocol:'t Gluten.runtime
                        ^^^^^^^^^^^^^^
Error: Unbound module Gluten
File "src/vendor/httpaf/lib/reqd.ml", line 235, characters 31-44:
235 | let try_with t f : (unit, exn) Result.result =
                                     ^^^^^^^^^^^^^
Error: Unbound type constructor Result.result
make[1]: *** [build] Error 1                     
make: *** [docs] Error 2

✅ OpenSSL

EDIT: Oops. Seems like I hadn't actually installed in on this machine.

I ran into this issue upon running opam install --deps-only ./dream.opam --with-test. Looks like it's unable to find openssl in my path?

❯ opam install --deps-only ./dream.opam --with-test
The following actions will be performed:
  ∗ install conf-libssl  4
  ∗ install ssl          0.5.13
  ∗ install lwt_ssl      1.2.0
  ∗ install dream-httpaf 1.0.0~alpha2
===== ∗ 4 =====
Do you want to continue? [Y/n] y

<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><>  🐫 
⬇ retrieved ssl.0.5.13  (cached)
⬇ retrieved lwt_ssl.1.2.0  (cached)
⬇ retrieved dream-httpaf.1.0.0~alpha2  (cached)
[ERROR] The compilation of conf-libssl.4 failed at "sh -ex ./homebrew.sh check".

#=== ERROR while compiling conf-libssl.4 ======================================#
# context     2.1.4 | macos/x86_64 | ocaml-base-compiler.4.12.0 | https://opam.ocaml.org#88362781
# path        ~/dev/oss/dream/_opam/.opam-switch/build/conf-libssl.4
# command     ~/.opam/opam-init/hooks/sandbox.sh build sh -ex ./homebrew.sh check
# exit-code   1
# env-file    ~/.opam/log/conf-libssl-46563-ea0c79.env
# output-file ~/.opam/log/conf-libssl-46563-ea0c79.out
### output ###
# ++ brew --prefix openssl
# + brew_pkg_config=/usr/local/opt/openssl@3/lib/pkgconfig
# + case "$1" in
# + test 1 '!=' 1
# + export PKG_CONFIG_PATH=/usr/local/opt/openssl@3/lib/pkgconfig:/Users/ekander/dev/oss/dream/_opam/lib/pkgconfig:
# + PKG_CONFIG_PATH=/usr/local/opt/openssl@3/lib/pkgconfig:/Users/ekander/dev/oss/dream/_opam/lib/pkgconfig:
# + pkg-config --print-errors --exists openssl
# Package openssl was not found in the pkg-config search path.
# Perhaps you should add the directory containing `openssl.pc'
# to the PKG_CONFIG_PATH environment variable
# No package 'openssl' found



<><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><>  🐫 
┌─ The following actions failed
│ λ build conf-libssl 4
└─ 
╶─ No changes have been performed

…heming

aantron · 2023-04-28T06:16:17Z

The docs error is a mismatch during the rewriting of the docs (fixing up odoc's output). Are you on odoc 2.0.2?

The switch has to be less than 5.0.0, because odoc 2.0.2's deps are incompatible with 5.0.0 IIRC. So I use 4.14.1. You shouldn't have to do --update-invariant or anything, at least I just start with a 4.14.1 switch.

It looks like you solved the submodule issue.

Not sure what is still left not working. OpenSSL?

aantron · 2023-04-28T06:17:12Z

I better add some notes to CONTRIBUTING.md.

lessp · 2023-04-28T08:15:47Z

The docs error is a mismatch during the rewriting of the docs (fixing up odoc's output). Are you on odoc 2.0.2?

Ah, right. Let me try that! 🙂

EDIT: I'm on odoc 2.2.0 via ❯ odoc --version

The switch has to be less than 5.0.0, because odoc 2.0.2's deps are incompatible with 5.0.0 IIRC. So I use 4.14.1. You shouldn't have to do --update-invariant or anything, at least I just start with a 4.14.1 switch.

Yeah, I'm not too familiar with Opam, but as far as I could tell, I was using 4.14.1.

It looks like you solved the submodule issue.

Not sure what is still left not working. OpenSSL?

All solved except for the probable odoc mismatch!

lessp · 2023-04-28T10:09:37Z

I better add some notes to CONTRIBUTING.md.

Was definitely not meant as critique, just thought it'd be helpful to myself and others to document any issues!

Follow-on to #268.

aantron · 2023-05-22T13:11:13Z

@lessp, thank you! Looks and works great. I added b55d191, which initializes the theme earlier, to avoid a flicker for users that have chosen the light theme. Without the earlier initialization, users with a light theme first see the page load with a dark theme, and then it flips to light.

I'm also slightly concerned about the appearance of the sun icon. But it looks a bit like a settings gear, which caused me to click it anyway, so that's probably fine.

lessp · 2023-05-22T14:34:28Z

@lessp, thank you! Looks and works great. I added b55d191, which initializes the theme earlier, to avoid a flicker for users that have chosen the light theme. Without the earlier initialization, users with a light theme first see the page load with a dark theme, and then it flips to light.

I'm also slightly concerned about the appearance of the sun icon. But it looks a bit like a settings gear, which caused me to click it anyway, so that's probably fine.

I had actually meant to come back to this and find a better spot for the toggle, but haven't really got around to it due to work. Not sure what state this was in! 😬

aantron · 2023-05-22T19:15:44Z

It's in a pretty neat state. You can see it live. If you have a good idea for where to move the toggle, you can ping this issue or maybe even PR it :) By the way, should the theme button show the icon for the theme you would switch to (as now), or the current theme? The latter seems more intuitive to me, but I'm not sure if there is some kind of usability convention I am not aware of.

lessp · 2023-05-23T09:19:53Z

By the way, should the theme button show the icon for the theme you would switch to (as now), or the current theme? The latter seems more intuitive to me, but I'm not sure if there is some kind of usability convention I am not aware of.

No idea, the former seemed more intuitive to me (the only reference that popped up was Play/Pause where if it's in a paused state, I believe it's more common to offer the action to Play, and vice versa), but 🤷

Also removed the shadow on the <h1> element. It was probably left over from an early version of the dark theme, before Dream's alpha 1 release. Resolves aantron#235. Co-authored-by: Anton Bachin <antonbachin@yahoo.com>

Follow-on to aantron#268.

Docs: Add light-theme and respect user preference

e37ca02

lessp commented Apr 26, 2023

View reviewed changes

docs/web/site/docs.css Outdated Show resolved Hide resolved

Docs: Remove incorrectly referenced 'h1-text-shadow'

741a597

Tweak anchor and nav bar border colors

046d6de

Also removed the shadow on the <h1> element. It was probably left over from an early version of the dark theme, before Dream's alpha 1 release.

Merge branch 'master' of https://github.com/aantron/dream into docs-t…

4213fc7

…heming

lessp added 4 commits April 28, 2023 14:45

Merge branch 'docs-theming' of github.com:lessp/dream into docs-theming

34221ef

Update code bg-color and remove unused CSS-var

ec99d26

Use toggle rather than user OS/browser setting

0a28e69

Move toggle out of media query

543bf8c

aantron mentioned this pull request May 2, 2023

Question：the document site only have darkness theme #235

Closed

aantron merged commit e529b0e into aantron:master May 22, 2023

aantron added a commit that referenced this pull request May 22, 2023

Docs: initialize theme earlier to avoid flicker

b55d191

Follow-on to #268.

dysinger pushed a commit to dysinger/dream that referenced this pull request Oct 2, 2023

Docs: initialize theme earlier to avoid flicker

4c5968c

Follow-on to aantron#268.

aantron mentioned this pull request May 27, 2024

Dream 1.0.0~alpha6 ocaml/opam-repository#25949

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add light-theme and use users preferred theme #268

Docs: Add light-theme and use users preferred theme #268

lessp commented Apr 26, 2023 •

edited

Loading

aantron commented Apr 26, 2023

lessp commented Apr 27, 2023 •

edited

Loading

aantron commented Apr 28, 2023

aantron commented Apr 28, 2023

lessp commented Apr 28, 2023 •

edited

Loading

lessp commented Apr 28, 2023 •

edited

Loading

aantron commented May 22, 2023

lessp commented May 22, 2023

aantron commented May 22, 2023

lessp commented May 23, 2023

Docs: Add light-theme and use users preferred theme #268

Docs: Add light-theme and use users preferred theme #268

Conversation

lessp commented Apr 26, 2023 • edited Loading

aantron commented Apr 26, 2023

lessp commented Apr 27, 2023 • edited Loading

aantron commented Apr 28, 2023

aantron commented Apr 28, 2023

lessp commented Apr 28, 2023 • edited Loading

lessp commented Apr 28, 2023 • edited Loading

aantron commented May 22, 2023

lessp commented May 22, 2023

aantron commented May 22, 2023

lessp commented May 23, 2023

lessp commented Apr 26, 2023 •

edited

Loading

lessp commented Apr 27, 2023 •

edited

Loading

lessp commented Apr 28, 2023 •

edited

Loading

lessp commented Apr 28, 2023 •

edited

Loading