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.

which restydoc
rpm -qf `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.

ssh ubuntu20-pkg

which restydoc
dpkg -S `which restydoc`

We can lookup the docs for the standard Nginx directive rewrite like this.

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.

restydoc -s listen

Or our OpenResty’s nginx module directives like init_worker_by_lua.

restydoc -s init_worker_by_lua

Standard Lua functions can be looked up too.

restydoc -s string.find

It is extracted from the official Lua 5.1 reference manual.

Or the standard Lua’s C API functions.

restydoc -s lua_gc

Or the LuaJIT’s Lua API extension.

restydoc -s ffi.cdef

Or OpenResty’s own Lua API extension.

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.

restydoc ngx_http_rewrite_module

Here we do not specify the -s option.

It’s much longer, as expected.

Or a whole Lua module.

restydoc resty.redis

This is the resty.redis library shipped with OpenResty.

Or specifying the Lua library name.

restydoc lua-resty-lrucache

To view all the options of restydoc, use the -h option.

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 The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.