Docr - Crystal documentation tool

Docr is a CLI tool for searching Crystal documentation, with version support for the standard library and documentation for third-party libraries/shards. It is inspired by go doc and this post[1] with support for Crystal path syntax in queries and library versioning.

A few side notes:

  • It is written in Go: ideally this would have been made with Crystal but the dependencies needed for this are not yet available (see this issue[2] for more information)
  • Colour options are not strict: there are some commands that will ignore ANSI colour overrides (via environment variable, --no-color flag, etc) due to the design of the application’s command line library; there isn’t an easy way to get around this so it won’t be fixed until the rewrite

Help with supporting the needed dependencies for the rewrite would be greatly appreciated. Happy Crystalling!

  1. Is there a cli tool to read documentation? - Help & Support - Crystal Forum ( ↩︎

  2. Rewrite in Crystal · Issue #1 · devnote-dev/docr ( ↩︎


Oh nice…

I wouldn’t mind a Crystal version being less colorful at first.


Yeah, sorry :sweat_smile: I will keep that in mind for the rewrite.

1 Like

See people come from go land recent days, is this great news?

Hi, please check the lucky website, It’s seem like there are some alternative shards for you porting.

e.g. glamour and chroma can be replace by GitHub - amauryt/cr-cmark-gfm: Crystal C bindings for cmark-gfm to work with Commonmark and Github Flavored Markdown ?

I’d rather not have to deal with a C library dependency, having a pure Crystal implementation would be better and Markd is sufficient for that, it just needs a few updates. Having glamour part of Markd or cr-cmark-gfm would not be a good idea maintenance-wise, especially given that both libraries aren’t actively maintained, but my port of Glamour will be implemented using Markd.

Just released v0.1.1 which should fix absolute paths not working properly on Linux systems. When getting started, you can now run docr update which will install create the necessary directories and import the necessary files to run. You can also now run docr env init if you just want to setup the Docr directories. Happy Crystalling!

1 Like

docr seem like create the wrong file attr folder on linux.(missing the r/w)

Following folder was created since i first run the docr.

╭─ 22:54  zw963 ⮀ ~/.config ⮀ ➦  
 ╰─ $ 2  sudo ls docr -alh
total 8.0K
d--x------  2 zw963 zw963 4.0K Apr 26 22:53 .
drwx------ 72 zw963 zw963 4.0K Apr 26 22:53 ..

I fix it my self, but then i run docr update again, it change to the wrong file attr again.

 ╰─ $ build/docr update
(i) no crystal library docs imported
(i) searching for crystal...
(i) found crystal version 1.8.0
(!) failed to get available crystal versions:
(!) open /home/zw963/.config/docr/versions.json: permission denied

This seems to be an issue with Go’s flag mappings for permissions, I’ve set them to raw bit permissions which should work now, but I wouldn’t be surprised if this breaks Windows builds at some point. Might be a something to keep an eye on for the rewrite.

1 Like

It works, thank you.

One more question, how to select following secondary puts method when docr info?

 ╰─ $ build/docr search 'puts'
Search Results:

def puts(*objects) : Nil

def puts(*expressions) : Nop

def IO#puts(string : String) : Nil

I don’t think there is a way to do that, but it is something I’ve been thinking about: filtering by method signature rather than just the name, or having some kind of --result <index> flag to specify which one you want. The latter could be implemented for the next release, whereas the former would be something for the rewrite.

Cool, something like specify index is very useful, make the former not so necessary.

1 Like

Hi, one more question, probably a little off-topic.

I used to use golang too, but I haven’t used it for a long time, and I’ve only done one small web projects.
yes, i don’t like it, probably it’s because I’m very familiar with Ruby, but not enough with golang, definitely don’t have the ability to write a tool similar to docr in go.

so, give me curiosity, you are already familiar with golang, and golang is far more popular than Crystal, why you would prefer to use Crystal over golang?


Go was the first statically-typed language I learned (coming from only dynamic languages) which I found hard, but I didn’t have any expectations about it because it wasn’t something I had any knowledge or experience with. In most cases you need to write quite a bit of “abstract code” with Go which can be very tedious (if err != nil), which has its benefits but isn’t helpful if you just want to do some prototyping. It’s also very easy to run into memory access issues with Go, and I’ve spent literal weeks debugging projects just to eventually find out that I implicitly dereferenced a nil pointer.

Crystal has a really nice syntax, it’s memory safe (well a lot more than Go is), and very type safe. You can do quick prototyping and easily refactor your project without having to think too hard about what needs to go into which folder/package/etc. The community is probably one of the best I’ve seen, although small, but it will grow in time as will the language.

1 Like

Thanks for response.

and I’ve spent literal weeks debugging projects just to eventually find out that I implicitly dereferenced a nil pointer.

This is one of key reason to use Crystal for me too, Although, I understand its benefits from the Dart programming language.

1 Like