I would like to create an global index for the Crystal lang documenation

Yes, this is possible. With the new navigation tabs this might become feasible. Before that the navigation tree would have been a way too big. The nav tree for the specification section would still be a huge beast with 100 entries up to four levels deep. But we can reduce the nav tree by merging subpages on the same topic (Condense spread-out topics into single-page documents · Issue #501 · crystal-lang/crystal-book · GitHub) and some re-organzation (Reorganize content structure · Issue #384 · crystal-lang/crystal-book · GitHub).

1 Like

This is what I had in mind:

https://devdocs.io/crystal/

Since it already exists, I won’t have to implement it myself after all.

I find this page very useful; shouldn’t it be linked to Crystal’s home page?

It’s unofficial, might be out of date. But it looks useful, maybe. It just combines two sites into one.

How is that different from Crystal 1.10.1 ?

Being a complete newbie to Crystal (and Rubuy too), I might be wrong, but I like it because:

  1. It compensates for the current luck of advanced auto-complete for VSCode, in the sense that it gives instant access to all classes and methods plus examples: Super-handy!

  2. It is very readable, really nice CSS.

PS: The more I study Crystal, the more I like it. I wrote a specialized (niche) search engine in Golang and I was wondering if I shouldn’t try to rewrite it in a language I feel more comfortable with. I tried Nim, Rust, Kotlin, Swift, but I believe I’ll settle for Crystal, because (for me) Crystal presents the best compromise between:

  • Simplicity.
  • Conciseness.
  • Expressivity.
  • Flexibility (classes, generics,…).
  • Performance.
  • Consistency (Crystal is written in Crystal).

And it has the fiber/channels similar to the goroutines/channels approach to asynchronism / parallelism which I find extremely useful.

3 Likes

That’s all true for https://crystal-lang.org/api/ as well. I’m trying to understand why you find DevDocs better and if maybe some of that better can be incorporated into crystal docs.

  • The style/CSS (I find it clearer).
  • The fact that the search box stays in place (search entry field) does not move along with the left-hand panel.
  • I might be mistaken, but the default content appearing in the left-hand panel seems more exhaustive (see the entry for Float, for instance).
  • It looks « flatter », for instance the entry for crypto opens all at once, whereas in the official doc, one has to navigate it level by level.

Of course, this is highly subjective.

@straight-shoota in devdocs the index includes the API docs and the language reference

There’s also a tree to the left.

I miss that tree in the reference docs… It gives a nice overview of everything

Okay, thanks. So it’s mostly little things, not a fundamental difference.

Yeah, there might be something to that, although it’s obviously subjective. Both are still very similar I think. Maybe the choice of font and font size plays a role for perceived clarity.

Maybe we could add that to crystal docs. Btw. you can already easily reach it from any viewport with shortkey s.

Yes, devdocs lists sub-headers (i.e. methods and macros) in the sidebar menu. I’m not a fan of that, and think that clutters the nav tree. For Float this might be o.k. but look at HTTP or Int namespaces with 380+ entries. That’s not useful at all. One part of the problem is that subtypes in the namespaces are untested.

For small sub-trees, this looks like an obstruction, but for bigger sub-trees it’s a feature. The largest sub-tree in stdlib API docs is probably HTTP which fills about the entire viewport height on a typical widescreen monitor. That might be okay. But some shards have way more complex sub-trees. I wouldn’t want the entire tree to unfold when there’s dozens of entries and sub-entries.

Ah, I didn’t catch that. It doesn’t do a very good job at integration, tho. The hierarchical and sequential context are lost in the flat, alphabetically sorted nav list.

1 Like

Perhaps, a good solution would be an interface which would offer the choice between the two styles of indexes.

  • I suspect that the compact, deeply indented tree structure, is handier for someone who is already quite familiar with the language and conversely.

  • After all, a book for instance has sometimes a summarized table of contents and additionally a more detailed one.

Since we’re listing different options, let’s not forget Top-level namespace - Crystal

And oh yeah, I only now realized, it has Summary - Crystal which is the other half of what you want

I might be mistaken, but the default content appearing in the left-hand panel seems more exhaustive (see the entry for Float, for instance).

Very useful with at least 2 use cases:

  1. I know there’s a method that does what I want but I can’t remember the name so search is useless aka “I’ll know it when I see it”.
  2. Not familiar with a class (or beginners) but want a quick overview of “what can I do with this class” without reading the entire class doc.

devdocs is my new crystal API bookmark because of it.

The instance method summary of the official Crystal API docs is too noisy for #1 and not as useful for #2.

Improvements could be made to devdocs.io classes with large lists by:

  • Putting subclasses within a tree exactly as the official Crrystal API document does.
  • Removing “Show more”. Show the entire list. Otherwise why did I expand the tree? I can click to collapse if not wanted, but clicking 5+ times to see the end is not user friendly.

Perhaps Crystals docs could merge some of these UI elements by including an optional expandable method list on the left.

How useful is it? 2 people so far find it useful and the official docs less so.