Lookup OpenResty Documentation on Terminal with restydoc
This tutorial demonstrates how to use OpenResty’s restydoc
command-line utility to quickly lookup OpenResty documentation for Nginx modules, Nginx configuration directives, Lua API functions, Lua C functions, Lua modules, and many more. The restydoc
tool was originally inspired by Perl’s perldoc
utility.
1 | which restydoc |
The restydoc
utility is shipped with OpenResty itself. The package name is openresty-doc
on Yum-based systems.
The package name is openresty-restydoc
on Debian-based systems, like Ubuntu 20.04.
1 | ssh ubuntu20-pkg |
We can lookup the docs for the standard Nginx directive rewrite
like this.
1 | restydoc -s rewrite |
Note the -s
option, which means “section”.
It is extracted from the official Nginx documentation. Under the hood, it invokes the less
utility.
We can use the space key to switch to the next page.
We use the q
key to quit.
Or the standard Nginx’s listen
directive.
1 | restydoc -s listen |
Or our OpenResty’s nginx module directives like init_worker_by_lua
.
1 | restydoc -s init_worker_by_lua |
Standard Lua functions can be looked up too.
1 | restydoc -s string.find |
It is extracted from the official Lua 5.1 reference manual.
Or the standard Lua’s C API functions.
1 | restydoc -s lua_gc |
Or the LuaJIT’s Lua API extension.
1 | restydoc -s ffi.cdef |
Or OpenResty’s own Lua API extension.
1 | restydoc -s ngx.re.match |
All the restydoc
commands above specify the -s
option. This is because the displayed docs are all sections from some larger documents.
We can view large documents like a whole Nginx module’s.
1 | restydoc ngx_http_rewrite_module |
Here we do not specify the -s
option.
It’s much longer, as expected.
Or a whole Lua module.
1 | restydoc resty.redis |
This is the resty.redis
library shipped with OpenResty.
Or specifying the Lua library name.
1 | restydoc lua-resty-lrucache |
To view all the options of restydoc
, use the -h
option.
1 | restydoc -h |
That’s all I’d like to cover today. Hopefully you’ve found this tool useful.
If you like this tutorial, please subscribe to this blog site and our YouTube channel. Thank you!
About This Article and Associated Video
This article and its associated video are both generated automatically from a simple screenplay file.
About The Author
Yichun Zhang is the creator of the OpenResty® open source project. He is also the founder and CEO of the OpenResty Inc. company. He contributed a dozen open source Nginx 3rd-party modules, quite some Nginx and LuaJIT core patches, and designed the OpenResty XRay platform.
Translations
We provide the Chinese translation for this article on blog.openresty.com.cn. We also welcome interested readers to contribute translations in other natural languages as long as the full article is translated without any omissions. We thank them in advance.
We are hiring
We always welcome talented and enthusiastic engineers to join our team at OpenResty Inc.
to explore various open source software’s internals and build powerful analyzers and
visualizers for real world applications built atop the open source software. If you are
interested, please send your resume to talents@openresty.com
. Thank you!