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!
