altai-man / docs.raku.org Goto Github PK

(My personal wish, YMMV)

How any search engine (like duckduckgo) offers a search bar to the user:
you open their webpage, and the search field is right before you, and it is focused straight away and webpage is ready to accept your keyboard input, you start typing immediately without any additional movements.

This is the right way (IMHO).

With https://docs.raku.org/ you fireup the page, the search bar is there waiting for input but it is not focused.
Darn it! Excessive mouse movements and a click or 2 tab presses are needed to focus.

Now take your temporary http://164.90.207.89:10010/
With wide enough screen, the search bar is there, but not focused,
you need excessive mouse movements and a click or 8! tab presses.
With narrow screen, the search bar isn't even displayed, so you need to move that mouse into the corner, then click and, guess what? You get the search bar in the opposite corner of the pane! Your cursor loves to be moved across the screen forth and back! 😄

Please note that with the window size as in the screenshot, there is enough space for the search bar.

Search bar not displayed
(Also please note vertically misaligned Learn more button under Language Reference & Tutorials)

Search bar in the opposite corner

A keypress like / for triggering search might mitigate the issue, yet why hide that poor search bar in the first place?

Search bar animation. Why? I come for docs, and want them promptly. With animations I get distracted and they make me wait while animation finishes.

Github search bar like on this page is also expandable, but it is not that bad as it expands left-to-right, and the input cursor stays in place.
With your temporary http://164.90.207.89:10010/ the bar expands right-to-left, and the cursor flies away from the spot where it was which distracts and makes me seek that cursor again.

Recap:

• Please make search bar ALWAYS VISIBLE.
• Please make search bar FOCUSED on newly-opened pages.

There is a ticket Raku/doc#1086 requesting a very neat, yet a bit intricate feature. In short, it suggests that additional information in the search query (for both quick search field in the header and the search page (see #14)) should narrow the search.

Current categories we have now are, alas, quite muddy, but hopefully this will be fixed sooner or later.

A number of rules can be imagines, but let's go with this:

• . (a dot) before the query suggests to search in method category only
• & before the query suggests to search in routine category only
• () at the end suggests both method and routine categories only
• :: at start suggests role, class, package categories only

It will be also pretty cool to have simple tests for this around.

Using symbols to select a specific catgory ((), &, .) in the search field isn't working as expected.

This is a big and interesting ticket.
There is a long term demand (Raku/doc#1099) for serving a dynamic page for search.

It can be either JS-based or backend based, but looking at various options I myself did not really find anything that seems okay-ish enough just as JS we use now.

Right now, we serve such a static page:

We need pieces of JS to handle everything on it. This includes:

• On typing in the search field we should query our JS search data and display formed results according to the layout in the UI mock-up.
• Results counter is at the top right, it should be updated.
• It has to be able to know about specific category chosen at the top left select and filter out results.
• If the page is opened with q=fofofo query parameter, JS has to understand this, pre-fill the input with fofofo and display results for that, so that we could point this template to other search engines.

What is interesting here is that we want to avoid duplicating lots of code from search.js we have now (it will be inevitable anyway, but let's try to make the code structure as organized as possible).

in chrome (on mac)
set size to 970x976 (e.g.)
click on the hamburger
click in search
type test, hit the magnifying glass icon
search results show up under the input box, but you can't scroll to see them

But we don't have that and I pretty much suspect it is a firm bottleneck for the huge page rendering performance.

If you keep the style attribute (style="width: 200px;") within the navbar search field, it will break input size on small screens.

Scenario to reproduce

1. Open browser inspector/devtools and choose 720p screen.
2. Use horizontal orientation.
3. Type something to search in navbar.
4. Deselect the search field and switch to vertical orientation in inspector/devtools.
5. Open a hamburger menu.

So things like || are not escaped.

They work not worse than they were on the previous website locally, but with styles not published do not make a lot of sense, so adapt and publish highlighting styles file.

The task is to think of something SEO friendly and tinker on the implementation.

So I have been getting this error since using the site. It usually doesn't appear right away, but after going to a few links on the page to other parts of the site. I am using Firefox 87.0 with Pop_OS! latest. I'm happy to provide more data if needed.

The only pattern I can discern is that if I start a fresh session or go to https://docs.raku.org/ directly I can get to a few pages before getting the error, and then to continue using the site I have to go to that link again directly. But now however I am noticing that if I come directly to that link, sometimes I get what appears to be the CSS failing to load:

I'm also getting some JS errors:

And after refreshing I get:

Would be nice to have two ways to report issues, one for the content (at raku/doc) and one for any site issues (here).

Right now, when Run button on the example is clicked, nothing visually says about what happens... And then the result appears. However, it may take a long time and it's a bad thing to make the user worry about what is happening.

Thus we need to give a clean visual hints about what's happening, say a spinner with "We process your request blah blah" kind of thing.

The relevant code is at https://github.com/Altai-man/docs.raku.org/blob/master/static/js/core.js#L84-L109

Where in this repo should documentation content be written? And what format, Pod?

e.g.: http://164.90.207.89:10010/programs/01-debugging

link at the bottom points to:

http://164.90.207.89:10010/programs/%7B%7BpodPath%7D%7D

but should probably point to the pod6 file in github for raku/doc (bonus points for pointing to a branch if that's what was used)

It is not served and apparently we should.

http://164.90.207.89:10010/

clicking on "Learn More" in any card takes me to the apppropriate section, but:

clicking on "Type Reference" does nothing.

I expect the text of the card and the icon to go to the same location as the learn more button.

Zeal is an offline documentation browser for software developers.
https://zealdocs.org/

Dash is for macOS
https://kapeli.com/dash

Docset Generation Guide
https://kapeli.com/docsets

With breaking I mean that the dropdown doesn't appear and when pressing enter the letters that were there when the dropdown worked for the last time is searched, not the current word.

"garba" works
"garbag" doesn't work, searches for "garba"
"garbage" works
"garbage-" doesn't work, searches for "garbage"
"garbage-c" and anything longer doesn't work, searches for "garbage"

We have docker instructions for doing the initial build of the site - because this takes a while, we probably need instructions on how to do the minimum to update the docs site; I'm guessing we also want those instructions to end with swapping out the old running site for the newly updated container, but I'm not 100% sure.

Paragraphs are not rendered. See e.g. http://164.90.207.89:10010/language/syntax vs https://docs.raku.org/language/syntax and https://github.com/Raku/doc/edit/master/doc/Language/syntax.pod6

https://rakudocs.github.io/perl6.html
It hasn't been updated for looong.

Basically Raku/Pod-To-HTML#82

After following README, last instruction is:
DOCKY_PORT=20000 DOCKY_HOST=localhost raku -Ilib service.p6
Results in errors:
'Docky::Renderer::TOC' cannot inherit from 'TOC::Calculator' because it is unknown
I can remove is TOC::Calculator from Docky::Renderer::TOC without any obvious immediate errors.
But next error is from Docky::Renderer::Node which cannot inherit from 'Node::To::HTML' because it is unknown
Removing the inheritance leads to immediate errors with undelcared routines escape_id and node2rawtext
I can't find TOC::Calculator or Node::To::HTML in the Raku Modules directory.

http://localhost:10000/routine/coll

coll is a sorting operator that takes pairs of Strs, Cools or Pairs and returns an Order that uses the $*COLLATION order. The default behavior disregards diacritic marks and capitalization, for instance.

The Strs here renders more like Str s because of the padding

It should drastically improve loading time for our resources such as CSS.

There are two issues. For example, type dir:

^ It, apparently, tries to sort categories alphabetically, but I believe we want to sort them by if there are exact matches (first) or the string contains (next) and then the rest.

So for dir you will see:

Routine
dir (exact match)
(other results from this category)

then

some category blah blah
blah blah dir (the string contains the exact word, but has other things besides) - a function blah blah

then

some category blah blah
DIgital Routine (no exact match at all, just fuzzy)

But when you look at it closer, it seems like items from the same categories are not grouped properly? We should investigate why it behaves in this strange way. Yes, there are both "Routine" and "routine" categories due to Raku/doc#1410, but even so it is odd to have the same category items in different places.

On my machine it measures like 9 seconds to display /type/Array and 1 second after it is cached. Both cases are clearly unacceptable, so we need to do a wide range of efforts to make it much faster.

Possible ideas investigated:

• Using Cro::WebApp over Mustache shaves off seconds. Blocked with Raku/Pod-To-HTML#82
• About 80% of time is spent awaiting for the coffee script to highlight code snippets, with over 300 of them on a page it takes a lot. The temporary (?) solution possible is to heavy cache results and pre-fill cache on the app start. With a couple of docker containers in kubernetes chances of downtime won't be too high.

The demo website we have now resides in a Docker container with network share, the cache is heated.

However, for some reason serving pages, even static ones, is very slow, 100-1000x slower than what it looks like at localhost set up in a similar way (running via Docker, not a real thing which is even faster).

We need an infra pro to investigate what causes this slowness and find a solution.

Is this repo licensed under the same Artistic License 2.0 as Raku/other main Raku projects? If so, I'd be happy to submit a PR adding the LICENSE and updating the META6.json – but I don't want to assume, since it's your project and you get to pick the license 😁

Somehow it magically works with the old website, but Cro cannot parse it.

Not all examples generate output (or are intended to be standalone runnable snippets). It would be nice to be able to mark certain examples as runnable or not (depending on what we make the default).

Something like :!runnable on the example's Pod?

Besides browser searching on a page, it is possible to filter Table of Contents.

Current implementation can hide subtrees of headers that do not match the query, but we can provide a much better experience here.

For example, open /language/functions page.

While ideas are welcome, main points can be:

• Highlight in bold or some other clear visual way suitable entries matching.
• Hide not matching subtrees on each level, not just the first one (as done now).
• Review / cleanup the code.

Current implementation resides at https://github.com/Altai-man/docs.raku.org/blob/master/static/js/core.js#L179-L206 and wants some love.

On mobile the TOC can overlap the content. I sometimes are confused for a bit by the result. In the above case wondering, why the operator precedence table contains only examples.

My spontaneous idea would be to hide the TOC by default when it would overlap the content.

404s should look more like:

https://docs.raku.org/404

My personal token is probably not a great way to (ab)use resources of kind folks at glot.io.

Sources are available at https://github.com/prasmussen/glot so we can try to host it ourselves with just parts we need.

Investigate how are they requested and write a serving route!

e.g. http://164.90.207.89:10010/language/quoting#index-entry-heredocs_:to-Heredocs:_:to

When going to a new page, e.g.:

http://164.90.207.89:10010/programs/01-debugging

the left nav pops out, obscuring the content. It would be nice if when expanded, all content was still visible (or, if that's problematic, if the page started with the nav hidden)

The original intent was to have a search input similar to github one - it does not take a lot of space, but when clicked it is expanded.

The code that tries to achieve that resides at https://github.com/Altai-man/docs.raku.org/blob/master/static/js/core.js#L210-L229 but it is clearly buggy even if you are not very persistent - a couple of clicks due to slowness of the animation is enough to confuse the search input, break the page layout and cast demons from other world.

This ticket is resolved if this behavior is done in a stable, cross-browser and eye pleasing way with minimal efforts.

It includes:

• Working out a good enough spec for metadata of this
• Talking it over and merging it for at least some cases in main docs repo
• Adapting our rendering code and UI to match the spec

Runnable code snippets without newlines and the contents is all jumbled up.

if I go to a page and hide the left nav, clicking on any other link in the doc site re-opens the left nav.

E.g.:

http://164.90.207.89:10010/routine-term

nav is open. hide it.

Click on "routines" at the top. left nav is open again.

Hide it. surf to http://164.90.207.89:10010/routine/now ; left nav is open again

e.g.

http://164.90.207.89:10010/routine/dirname

click on "Run", get

Output
Error occurred: error

Seems to be pervasive. (not sure if this happens locally as well)

Getting the following error when running the command DOCKY_PORT=20000 DOCKY_HOST=localhost raku -Ilib service.p6

Invalid typename 'Pod::To::HTML::Renderer'
at /home/mydir/docs.raku.org/lib/Docky/Renderer/Page.pm6 (Docky::Renderer::Page):4

Searching for "scheduler" and then clicking on "$*SCHEDULER" leads to http://164.90.207.89:10010/language/variables#index-entry-$*SCHEDULER But that anchor doesn't exist. http://164.90.207.89:10010/language/variables#$*SCHEDULER exists though.

We have 404, 500 is a must as well.

We want to log 404 errors to add redirects wherever usable and 500 errors to fix bugs.

Technically it is just extending handlers at https://github.com/Altai-man/docs.raku.org/blob/master/lib/Docky/Routes.pm6#L26-L29 with something writing a log somewhere where it is nicely visible. Potentially with squashing duplicated errors? Something fancy is welcome.

The redirect checking will be more interesting in case of superseding the original docs website, but we need to have it structured sooner than that.

Not all dependencies are listed in the README file for following the instructions.

Without node, there is a Node:from<bin> error
Without graphviz, there is a dot:from<bin> error
Without coffeescript, the pages hang for a long time before loading.