devnote-dev / docr

A CLI tool for searching Crystal documentation

Docr

docr is a tool for searching Crystal API and shards documentation from the command line.

Installation

See the releases page for available binaries.

From Source

Crystal v1.8.0 or above is required to build Docr.

git clone https://github.com/devnote-dev/docr
cd docr
shards build

Usage

By default, Docr comes with no libraries, but you can easily import the standard library documentation using docr update. This command will search for the crystal executable on your system and import that version of the API documentation. If the executable isn't found, it defaults to the latest available Crystal release. If you want to import the standard library directly or a specific version, you can do so with the docr add crystal <version> command (also accepts "latest" as a version).

You can also import third-party libraries (or shards) using the docr add command:

After importing the libraries you want, you can simply lookup or search whatever you want! Use the docr search command to search for all types and symbols matching the query, and the docr info command to get direct information about a specified type or symbol:

Both the info and search commands support Crystal path syntax for queries, meaning the following commands are valid:

• docr info JSON::Any.as_s
• docr info JSON::Any#as_s
• docr info JSON::Any as_s

However, the following commands are not valid:

• docr info JSON Any as_s
• docr info JSON Any.as_s
• docr info JSON Any#as_s

This is because the first argument is parsed as the base type or namespace to look in, and the second argument is parsed as the symbol to look for. In the first example, JSON::Any is the namespace and as_s the symbol, whereas in the second example, JSON is the namespace and Any as_s is the symbol, which is invalid. This doesn't mean you have to specify the namespace of a symbol, Docr can determine whether an argument is a type/namespace or symbol and handle it accordingly.

Contributing

1. Fork it (https://github.com/devnote-dev/docr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Devonte W - creator and maintainer

This repository is managed under the Mozilla Public License v2.

© 2023 devnote-dev

docr's Issues

Hi, ameba 1.4.3 will broken on Crystal 1.9.2, need update to 1.5.0 instead.

Check crystal-ameba/ameba#372

Rewrite in Crystal

Ideally this project would have been written in Crystal, but the dependencies required for this are not yet available:

• icyleaf/markd#53 No longer using this library
• Port glamour to Crystal (Marker)
• Port Chroma to Crystal (or some basic form of it)

docr add crystal 1.9.2 failed.

 ╰─ $ docr add crystal 1.9.2
(i) importing crystal version 1.9.2
(i) fetching available versions...
(!) crystal version 1.9.2 is not available
(!) run 'docr check' to see available versions of imported libraries

 ╰─ $ crystal version
Crystal 1.9.2 [1908c816f] (2023-07-19)

LLVM: 15.0.7
Default target: x86_64-pc-linux-gnu

Current Crystal version is 1.9.2, was compiled on my local with document.

In fact, docr check command not available too.

`docr add crystal 1.7.3` throws ".config/docr/versions.json: permission denied"

It looks like ~/.config/docr is being created with a permission of 0100. I've tried changing it to 775 or something, but it just switches it back.

Support FZF

Implement support for fzf. I'm not entirely sure what this is for as I don't use it, so it won't really be high priority.

Scope-aware queries

Currently you can include the . and # symbols in type/symbol queries when searching or getting info. However, these are not scope-aware, meaning that using a query with . will search for class methods/declarations and instance methods/declarations. For the sake of convention consistency, this should be re-evaluated to be scope-aware, so:

• docr info String.to_s should look for the class method;
• docr info String#to_s should look for the instance method;
• docr info String to_s should return the first available result

Having some form of UI to indicate similar available methods would also be useful here.