Documentation Channel for #raku | This channel is logged | Roadmap: github.com/raku/doc/wiki
Set by [Coke] on 23 May 2022.
00:18 raiph joined
rf Looks good, good work folks! 00:18
raiph Hmm. Has there been an attempt at the doc site switchover? 00:19
Is it expected that some/most links will 404 for a while? 00:20
For example: docs.raku.org/language/concurrency#Supplies
OK, backlogging and I see there is something going on. 00:22
rf Another issue is there are no typegraphs on the classes :O 00:23
raiph Which is great news, but I just posted a comment with 6 links to major Raku features and 5 are 404ing. 00:24
Perhaps it's the caching issue I see liz mentioned?
(The comment is www.reddit.com/r/ProgrammingLangua.../ja5ht58/) 00:25
Geth ¦ doc-website: coke assigned to dontlaugh Issue URLS shouldn't require .html github.com/Raku/doc-website/issues/147 00:26
[Coke] github.com/Raku/doc-website/issues/147 - 00:27
coleman: this is the issue reported by ugexe and raiph. URLS currently require .html and shouldn't.
coleman I'll take a look at a rewrite rule 00:28
[Coke] Thanks! 00:29
raiph Ah, well I think that'll break pretty much every doc link I've ever written. :)
coleman womp womp
raiph Yeah, quick search of my /r/programminglanguages comments shows it breaks all links for last year. 00:33
All doc links that is. 00:35
 My search for '.html' did match a dozen comments with links that end '.html' but they're not doc links.
But I'm find with every comment I've ever written being broken if docs are moving in the right direction. :) 00:36
s/find/fine/
[Coke] Hopefully this will be a straightforward fix. 00:37
raiph Hmm. Same will be true of all my StackOverflow answers.
[Coke] Sorry, should have caught it before go live.
Yes. All links. I get it. :)
cfa regarding the switchover, imo the stylesheet issue is fairly urgent
just take a look at docs.raku.org/type/Regex.html
raiph Nothing to be sorry about, gotta be bold.
[Coke] "the stylesheet issue" ?
#144? 00:38
cfa yes
docs.raku.org/language/regexes.htm...al_adverbs 00:39
the majority of examples on that page are incorrectly rendered
and... it's a fairly significant piece of documentation
[Coke] *how* incorrectly? The ticket indicates it's just a whitespace issue 00:40
Are you saying code is missing?
cfa no, it's a spacing issue
but the examples are badly rendered
[Coke] if it's just spacing, I don't think that's urgent.
define "badly"
cfa hard to read
[Coke] Maybe doing a screen grab and highlighting the issue would help underscore how badly broken it is.
cfa well take a look
it's obvious 00:41
[Coke] cfa: looks fine here. Please take a screen shot, and include info on browser, port size, etc.
raiph I just looked at it seems (relatively) great to me.
[Coke] cfa: I'm telling you, it looks fine here.
raiph I mean the spacing is weird.
[Coke] so please take the screenshot and provide the sizing & browser info.
cfa it looks the same in two browsers and isn't what's in the underlying code block
[Coke] but looking at this in my browser: it's absolutely not urgent.
raiph But cut/paste into glot.io worked fine. 00:42
cfa docs.raku.org/language/regexes.html#Samecase
yes, it's css padding not insertion of additional spaces
so it'll copy out fine
it just renders poorly
raiph Agree with Coke
cfa it's a regression in readability of code examples
if you disagree that's fine; i've filed an issue and defer to you
[Coke] cfa: pics or it didn't happen.
cfa sigh 00:43
raiph :)
cfa i spent time filing an issue already
[Coke] and I can't do anything with it.
cfa "or it didn't happen" is dismissive
[Coke] I don't even know what browser you're on. what OS. it looks fine to me and someone else here.
cfa no
"I mean the spacing is weird" was what raiph said
[Coke] cfa; yes, well, I'm frustrated to have to say "please submit a screen shot" multiple times.
cfa okay 00:44
[Coke] If that's the ticket we have, we'll fix the spacing eventually, for sure.
raiph coke: it doesn't look "fine" to me in an ideal sense
[Coke] but for now, the ticket as reported is not urgent.
cfa it looks worse than the original doc site, and doesn't represent what's in the underlying code example
i don't know why this isn't considered urgent or important but there you go
raiph but it's not important or urgent in my view
cfa fair enough
[Coke] Are you saying that lines of code in raku/doc source are not in the rendered sample? 00:45
cfa no
[Coke] then what do you mean by "doesn't represent" ?
cfa i'm saying that if the source looks like this: 'x y' then it may be rendered like this: 'x y'
[Coke] an annotated screen grab would definitely help me understand what you're talking about.
cfa which is what's happening in multiple places on the regex page
yeah okay i'll find somewhere to upload later on today 00:46
[Coke] Thank you. That was not clear from your previous complaint.
cfa when the original doc site was up the comparison was obvious from the urls
complaint?
[Coke] "bug" 00:47
cfa okay 00:48
raiph i've got a png, where do i share it?
[Coke] a screen grab or a more detailed explanation would have been very helpful. I saw "padding", and yes, there's definitely more padding *around* the examples. highlighting the actual text of the problem, now I hopefully see what you're pointing out
github.com/Raku/doc-website/issues/144'
github.com/Raku/doc-website/issues/144
Geth doc-website/rewrite-rules: 9e98814f4c | (Coleman McFarland)++ | 3 files
Add rewrite rule
 00:49
doc-website/rewrite-rules: 1d9656ba8a | (Coleman McFarland)++ | default.conf
Add root
cfa thanks raiph
[Coke] raiph++
Definitely, that's worse than what I thought the original bug was saying, and what I saw just now looking at the page. 00:51
cfa i provided an example of the underlying html and the exact css that was causing the problem 00:53
the screenshot is very helpful, i agree
anyway, as a user i find this rendering issue significant
raiph Imo it looks awful but I am confident it's of little concern. 00:55
cfa :)
raiph Everyone will hate it. 00:56
So everyone will want it fixed.
So coke doesn't have to worry about it. :)
Most of the links to the doc from StackOverflow being broken? 00:57
[Coke] yes, we know, coleman is working on it now
raiph That's still not overly concerning.
Because everyone will hate it and focus on it too. :) 00:58
[Coke] ? I think that does make it concerning.
raiph Coke: and as you said, you don't think it'll be too challenging.
[Coke] ... which is why we're working on it.
raiph: ah
raiph Coke: Yeah, I worry about the stuff that is difficult. 00:59
Like people getting on with each other.
[Coke] cfa: so, yes, that seems more than just cosmetic, hopefully someone can fix it in the next few days
raiph And getting past the point the doc is essentially frozen.
cfa [Coke]: thanks 01:00
coleman you just gotta rip the bandaid off
raiph Coke: yes, these are things you, cfa, coleman, richard, altai-main, ... have guided us through.
cfa apologies for being crotchety
raiph now *that* is important
[Coke] cfa: same 01:01
In my defense, I *am* old. :)
raiph :)
cfa and in my defense, i'm cantankerous 01:03
no wait
[Coke] ^_^
it's been a hot minute since I've done front end web UI, but I suspect we need to take the new style sheet that includes .section and carve out an exception for anything under <span class="source raku"> 01:04
cfa yeah 01:06
it's possible that other classes are affecting code blocks -- this is just the one i happened to notice while browsing the regex page
raiph past 1am here, thanks for doc reboot, zzz 01:20
01:20 raiph left
[Coke] ~~ 01:22
rf For the .html thing I think it should be as simple as a nginx try with a rewrite 01:27
coleman i'm bad at nginx; i'll push my branch 01:28
what's annoying me right now is the fact that nginx rewrites break unless it's port 80 or 443 01:29
which sucks for local dev
Geth doc-website/rewrite-rules: 3c537f74a6 | (Coleman McFarland)++ | default.conf
default.conf is what we need to edit

podman run -p 8080:80 -v ./default.conf:/etc/nginx/conf.d/default.conf \
   quay.io/colemanx/raku-doc-website		 01:30
coleman See the commit message for a way to try it out locally; you just need to mount in default.conf to the right place in the container 01:32
github.com/Raku/doc-website/commit...13b156512c
I'll keep working on it
Geth doc-website/rewrite-rules: a94b7ac7f3 | (Coleman McFarland)++ | 2 files
Add rewrites for .html; switch to caddy

This might seem like a drastic change, but it's really not a big deal, since we aren't using advanced configs anyways.
Caddy's configuration language is much saner for our use-case, and it even opens the door to api-based config.		 01:52
coleman See my PR for the likely fix for the rewrite thing 01:58
[Coke] if you're up for pressing the button I gave you, this is a great opportunity for a hotfix :) 01:59
well, technically we can go to dev-docs first
02:41 cfa left 02:45 rf left
[Coke] i don't have a place where I can run the site atm so I cannot test this. 03:42
I also need the button URL again, I think.
can you push it to -dev only? 03:46
or can I do that by merging the PR? 03:51
coleman merging does it 04:26
(after the build + systemd timer) 04:27
Geth doc-website/main: a12436b52a | (Coleman McFarland)++ (committed using GitHub Web editor) | 2 files
Add rewrites for .html; switch to caddy (#148)

This might seem like a drastic change, but it's really not a big deal, since we aren't using advanced configs anyways.
Caddy's configuration language is much saner for our use-case, and it even opens the door to api-based config.		 05:38
[Coke] ok, merged
so that goes right to docs-dev, and how do I get it prod? 05:39
"right to" in 30m or less
folks, I have to sleep soon; please check and report here if/when docs-dev.raku.org/type/Int starts working - as soon as we get confirmation that it looks good, someone can push to prod. 05:57
ok, it's working 06:10
coleman: before I press the button, it's "new build", yes? any env vars I need to set? 06:14
please go ahead and do the build yourself when you see this, and then you can walk me through pressing the button tomorrow. Thanks again! 06:15
07:46 sena_kun joined
lizmat I like the new doc site, but I have one beef with it 11:12
I sorta expected that opening the table of contents on a page, would reflow the page instead of hiding the left part of the page 11:13
if it *is* supposed to do that, then it doesn't do that on Safari
also see comments on fosstodon.org/@rakulang/109933636877354886 11:23
12:00 sena_kun left
tbrowder .tell [Coke] i am working on the table creator for a new PR and have followed yr instructions. one question remains: for the refresh operation, what response should there be for failure to download the Grammar.nqp file: die? throw? silence? warning? 12:32
ah, one more question: do you want to revisit the table name (and possibly its file name)? 12:35
.tell [Coke] ^^^
13:17 Voldenet joined
Voldenet I've noticed there's alternate stylesheets on the docs page now, but they can't be switched on firefox with theme switcher 13:18
you might consider adding those attributes to stylesheet: developer.mozilla.org/en-US/docs/W...yle_sheets
lizmat Voldenet: there's now also a repo for the website, perhaps a PR would be easy to make? github.com/Raku/doc-website/ 13:19
Voldenet now I see there's multiple css files for every theme, I'm not sure if stylesheets with the same title are grouped or not 13:21
lizmat wouldn't know 13:22
Voldenet I know, I'm checking how difficult it is to make this work 13:27
[Coke] Voldenet: also interested in PRs making it easier to do things. :) 13:28
13:52 rf joined
Geth doc/main: c7f4f08475 | (Brian Duggan)++ | CREDITS
update credits
 14:13
Voldenet Apparently just adding `title` attribute to stylesheet could work, but it would mess up js here 14:15
github.com/Raku/doc-website/blob/2...ore.js#L25
and I'm not sure how to force firefox to switch that style menu item in js 14:16
if it's even possible, since the feature itself is quite ancient
[Coke] ok, team, I can press a button to do a production release to fix the .html issue... but I have never done this before and might break it. My take is I should wait for coleman to press this button so I don't take the site down. Thoughts? 14:21
(I legitimately have a concern that it's asking for env vars but I don't know if anything is required there) 14:22
Voldenet I've tried building docs and failed with `Could not find Collection` 15:04
[Coke] did you install the deps? 15:16
... and do you mean doc-website?
Voldenet I did mean doc-website, and the solution was obvious: I needed graphviz 15:25
(graphviz was required by dependencies) 15:26
[Coke] (y) 15:27
... right, this isn't skype.
Voldenet (smile) 15:28
[Coke] ... and because I've got windows in my tmux path here, I can't paste in an emoji. :( 15:29
[Coke] needs to try again to get the stack working on mac. :| 15:31
Last time, got stuck in a maze of installing brew stuff that really didn't want to work on m2.
Geth doc/main: 9975aef048 | raiph++ (committed using GitHub Web editor) | CREDITS
Fix my email address

I don't want credit, but also don't want an email address that I consider lost to hackers (many years ago) to appear to belong to me.		 15:36
doc/main: e622fdff0f | raiph++ (committed using GitHub Web editor) | CREDITS
Fix my email address

Last "fix" wasn't correct. Sorry.		 15:37
coleman Pressed the button buildkite.com/raku/deploy-website-prod/builds/9 15:39
docs.raku.org/routines
seems to be a minimal fix
[Coke] 👍 - U+01F44D - THUMBS UP SIGN [So] 15:40
ah. Windows Terminal. Nifty. Only issue is that it makes my irssi in tmux session very laggy. but looks much better. 15:41
coleman No env vars are required for the build button 16:02
You can accept all the defaults, [Coke]
Geth doc-website/clean-up-caddyfile: c73c8ee592 | (Coleman McFarland)++ (committed using GitHub Web editor) | Caddyfile
Clean up Caddyfile

Remove unused "named" matcher rule. Fix spacing.		 16:06
[Coke] coleman: ok. I'll push the button if you're online now! 16:15
ah, you alrady did. thanks! 16:16
Voldenet there's a subtle bug in current theme handling in css
theme enforcing matches `light.css`/`dark.css`, but theme switching only `light`/`dark` 16:17
[Coke] when did you press the button - it's already fixed in prod 16:18
oh, 30+ minutes ago. 16:19
coleman Yea just got online 16:21
[Coke] Awesome. Few more bugs reported, one of which is Proc::Async (old style) vs. Proc/Async (new style) 16:23
Can probably fix that with the url rewriter also.
16:37 NemokoschKiwi joined
NemokoschKiwi Reading up on Bulma 16:37
Perhaps there are still possible gains for the sidebar... 16:44
[Coke] can someone verify that there are links of the form docs.raku.org/type/Proc::Async in the wild? 16:49
oh, right google. done, thanks.
Geth ¦ doc-website: dontlaugh self-assigned How to test changes to Tooling without affecting production? github.com/Raku/doc-website/issues/152 16:51
NemokoschKiwi There are links for everything - don't forget that we still have that button that just performs a google search with the content of the search bar 16:52
16:58 NemokoschKiwi left
Geth ¦ doc-website: coke assigned to dontlaugh Issue Proc::Async is generated as Proc/Async github.com/Raku/doc-website/issues/149 16:59
[Coke] if somone can test github.com/Raku/doc-website/issues...446693623, I'd appreciate it 17:09
Geth doc-website/reflog_defaults_to_doc_without_value: f833cb9f21 | finanalyst++ | Website/plugins/git-reflog/add-ref-hash.raku
make reflog fail softly if no reflog obtained
 17:20
doc-website/caddycolons: 50c6cfe515 | (Will Coleda)++ | Caddyfile
Support old-style Proc::Async URLs

go live only supported /Proc/Async, this restores the old functionality - many links to the docs depend on this style.
Part of #149		 17:24
doc-website/main: f05bc2f743 | (Will Coleda)++ (committed using GitHub Web editor) | Caddyfile
Support old-style Proc::Async URLs (#158)

go live only supported /Proc/Async, this restores the old functionality - many links to the docs depend on this style.
Part of #149		 17:25
coleman Hey Coke, you sunk my battleship! github.com/Raku/doc-website/pull/154
[Coke] yah, sorry 17:26
coleman If you're hacking on the Caddyfile later, you can remove that "named matcher" directive (the one with the @)
it's nbd. just cleanup.
[Coke] I thought about that but fixing prod bug outweighed config file cleanup, I thought 17:27
coleman I don't think Caddy cares about tabs/spaces fwiw
[Coke] the docker trick worked a charm, even on mac m2.
coleman++
coleman np. I wanted to mention it here because having dead code is confusing. especially since it's probably a new server for most.
I'll convert the Buildah script to a Dockerfile soon. 17:28
the command is
`buildah bud Dockerfile`
[Coke] needs to write all these things down so he doesn't ask coleman all the same questions again next week 17:29
Geth doc-website/clean-up-caddyfile: f05bc2f743 | (Will Coleda)++ (committed using GitHub Web editor) | Caddyfile
Support old-style Proc::Async URLs (#158)

go live only supported /Proc/Async, this restores the old functionality - many links to the docs depend on this style.
Part of #149		 17:30
doc-website/clean-up-caddyfile: 7380f0ff27 | (Coleman McFarland)++ (committed using GitHub Web editor) | Caddyfile
Merge branch 'main' into clean-up-caddyfile
coleman I was going to ask: where in the repo should we document that? 17:31
It should be at the bottom of the readme or in a CONTRIBUTING.md
Geth doc-website/main: c73c8ee592 | (Coleman McFarland)++ (committed using GitHub Web editor) | Caddyfile
Clean up Caddyfile

Remove unused "named" matcher rule. Fix spacing.		 17:32
doc-website/main: 7380f0ff27 | (Coleman McFarland)++ (committed using GitHub Web editor) | Caddyfile
Merge branch 'main' into clean-up-caddyfile
doc-website/main: 0f73ed75aa | (Coleman McFarland)++ (committed using GitHub Web editor) | Caddyfile
Merge pull request #154 from Raku/clean-up-caddyfile

Clean up Caddyfile
17:38 Geth left, Geth joined 17:41 raiph joined
Geth doc-website: finanalyst++ created pull request #159:
make reflog fail softly if no reflog obtained		 17:47
[Coke] coleman: or in the wiki. 17:48
coleman: is there a way to monitor if docs-dev has updated?
(and which commit id it's using, so I can verify if the next update includes your change to the Caddy file as well) 17:49
buildkite.com/raku/doc-website looks like "we build the site", but not "we deployed it to docs-dev" 17:54
ah, maybe it's hourly, and we're about 10m out.
coleman I think perhaps the build script can drop a comment in index.html or the git sha, or something like that 17:59
[Coke] there's a bug for that: 18:05
github.com/Raku/doc-website/issues/145 - you're right, that'd cover my ask 18:06
docs-dev.raku.org/type/Proc::Async works again
going to deploy to prod. 18:07
... once the hourly build finishes? 18:08
I am confused why docs-dev has my fix, which isn't content. 18:09
Geth doc-website: cfa++ created pull request #160:
Override CSS padding in `.raku-code` divs		 18:10
doc-website: voldenet++ created pull request #161:
add browser theme switching support		 18:11
18:11 cfa joined
cfa morning 18:11
coleman The hourly build includes everything that was added to Raku/doc 18:12
because the build script under bin_files does a fetch of the latest Raku/doc
Which is hard to see of course becuase of this github.com/Raku/doc-website/blob/m...build-site 18:13
Speaking personally, I'd like more comments all over this code to help me follow the thread :) 18:14
Voldenet I did the thing – it's not the code I'm proud of, but it works 18:20
I'm not sure what browsers are going to be supported, so no fancy js syntax
[Coke] We don't have an official list of supported browsers atm. 18:22
cfa: good to see you 18:23
pushing to prod...
wow, that's fast 18:24
cfa neat
[Coke] docs.raku.org/type/Proc::Async works again
cfa 👍
coleman thanks coke 18:29
18:46 sena_kun joined
Voldenet re themes: I wonder if it's a good idea to let colorschemed-versions be defined by plugins 19:21
> typegraph-dark.css typegraph-light.css>,
Not that anyone would add more themes to docs 19:23
coleman Coke, note that the prod deploy is a fire-and-forget trigger that instructs code running on prod to pull the latest container 19:25
so it is feasible that (at the moment) a green pipeline run masks a failure to pull the container
Unlikely, since the system has few moving parts and is simple. But be aware. 19:26
19:43 raiph left
[Coke] roger 20:00
22:04 raiph joined 23:10 sena_kun left
Geth doc-website/main: c9b7597928 | voldenet++ (committed using GitHub Web editor) | 2 files
add browser theme switching support (#161)
 23:34
doc-website/main: e5df30ed81 | cfa++ (committed using GitHub Web editor) | 6 files
Override CSS padding in `.raku-code` divs (#160)

  * Override CSS padding in `.raku-code` divs
  `.section` class padding currently interferes with the rendering of examples
  (see #144). Explicitly set it to `0rem` within code blocks.
The actual update is to `_highlighting.scss`; CSS files were regenerated by the `update-css` script.
  * Remove sourceMappingURLs		 23:37
doc-website/main: 0df605c4b6 | (Richard Hainsworth)++ (committed using GitHub Web editor) | Website/plugins/git-reflog/add-ref-hash.raku
make reflog fail softly if no reflog obtained (#159)
 23:38
23:48 raiph left

Powered by Cro and the Raku® Programming Language.

Please report any issues / comments / feature requests as an issue on App::Raku::Log.

Thank you!