The Crystal Programming Language Forum

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

Community
#1

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

The idea is to provide a web page (or a frame) pointing to the official doc, displaying the complete content of all the pages of the crystal documentation, in the shape one tree structure (global table of contents) with clickable links similar to e.g. the index for the Python doc: The Python Standard Library — Python 3.9.2 documentation

I am interested to do this for my own benefit, but I wouldn’t mind sharing it publicly in the shape of a Gitbulb web page.

In order to achieve this, I could navigate the existing Crystal documentation site recursively, or make a local copy (to scan the doc from the file system) or possibly download a zipped version of a doc if it is available.

  1. Would you be interested ?
  2. Would you recommend a way to proceed?
  3. Is the doc downloadable or available on github?
#2

Hi, and welcome!

What pages or site do you have in mind?

The language reference is already a tree and searchable: Home - Crystal

The standard library API is already a tree and searchable: Crystal 1.0.0

Are we missing something?

1 Like
#3

Home - Crystal is indeed an index with a tree structure, but points only to the “language reference” (specificatiin of the classes, methods, etc). It is a good reference, but not teaching material for beginners.

On the other hand, the didactic part of the documentation which explains the concepts of the language and their use, often using snippets to illustrate, is located in a collection of subdirectories located under the /syntax_and_semantics/ directory and, although they are all linked together (allowing to navigate individually from one isolated item to the next), there does not seem to be a global common index on one single page pointing all the html documents contained in the /syntax_and_semantics/ folder ( which would allow direct access rather Thant sequential access).

#4

What? No, it is the teaching material. I don’t know what you could be referring to.

They are not isolated, and additionally, every page contains the full table of contents on the left.

1 Like
#5

That table of contents is also available as a separate document Summary - Crystal but that’s mostly an implementation detail

1 Like
#6

The “summary” index is more of less what I had in mind.

However it does not seem to be linked to Crystal’s « home » page of « docs » page (at least not in a very visible way).

Python and Nim have indexes / listings pages which allows one to access any topic directly.

PS: A « Crystal by example » site would be cool too:

here is the Nim example:
https://nim-by-example.github.io/ and the Go example:

And the Go example:
https://gobyexample.com/

#7

Last but not least, links (from the « docs « page) to books and videos would be useful too:

Vidéos:

  1. https://youtu.be/DxFP-Wjqtsc

Books:

  1. Programming Crystal [Book]
#8

I don’t really get what you’re aming at. I understand you basically want a sitemap of GitHub - crystal-lang/crystal-book: Crystal docs at https://crystal-lang.org/reference. It happens to be at Summary - Crystal although it’s not reachable from the website navigation. We could add a link to that, but I’m not sure how useful it really is compared to the already existing navigation menu and search feature.

There’s an entire repository of it: GitHub - askn/crystal-by-example: Crystal By Example

#9

The Python document is actually not an index of the language reference, but the standard library. So [DocsGenerator] Add API index page by straight-shoota · Pull Request #9919 · crystal-lang/crystal · GitHub would perhaps be something you’re looking for?

#10

The Summary - Crystal is more or less what I had in mind.

  • The fact that I didn’t know about it, tends to indicate that it should possibly be more readily accessible from the home page(s) of Crystal.

  • An extended “crystal by example page” would be useful for beginners too.

#11

But what does this page give you that the existing navigation features don’t?

#12

This page provides me with a direct (random) access to the topics I am looking for regarding a given subject, without having to navigate from subject-to-subject via the doc section of the links. The links provided in the docs are more like a linked list, this is more like map or dictionary.

In other words, the links provided in the home pages are more like a manual which one reads sequentially, chapter by chapter, whereas this is more like an index or a table of contents which allows one to jump straight to a given topic of said manual.

#13

But isn’t the search feature much better suited at this? It even makes topics available that don’t appear in an individual page title.

The landing page and sidebar menu should be sufficient to give a high-level overview. The sitemap page sits somewhere in between sidebar menu and search.
Sure, it’s already available (even if just a byproduct) and we could just add a link to it. But I don’t really see much benefit. Especially considering that it would be incomplete in that sense that it only includes topics in crystal-book. API docs and installation instructions for example don’t appear.

#14

Here’s how I did it for my Axino framework:
https://serge-hulne.github.io/axino-docs/

I can do something similar for your Crystal and then we can decide if it is really as useful as I think.

#15

That actually looks like a pretty typical project readme. I don’t understand how that relates to a sitemap of the Crystal documentation.
It might really help if you could just make an example to show what you mean.

#16

I’ll try to put something together next week (I’m busy this week).

I’ll will keep you posted.

Thanks for your friendly answers!

2 Likes
#17

I will say with the old book you could kinda just scan the list and navigate to things at will, like you can with the summary page. The new book navigation has the collapsing sections which makes navigating like that a bit harder.

That said, I have been using search more than before and have been able to pretty easily find what I was looking for.

3 Likes
#18

This is the only thing I dislike about the new docs.

@oprypin is there a way to expand the left-side-bar tree inline?

2 Likes
#19

Perhaps, part of the problem (subjectively) is that I have used most of the major programming languages in the past, except for Ruby, therefore the Crystal doc seems a bit dodgy subjectively to me.

:-)

#20

These “collapsing sections”, I think, do not help a Crystal beginner (like me) to have a bird’s eye view of the language (unlike Python or Node or Golang or Rust).

1 Like