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!
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!
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.
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.
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.
I will keep that in mind for the rewrite.