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

screenshot 1

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
2
3
4
ssh ubuntu20-pkg

which restydoc
dpkg -S `which restydoc`

screenshot 3

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

1
restydoc -s rewrite

Note the -s option, which means “section”.

screenshot 6

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.

screenshot 8

We use the q key to quit.

screenshot 9

Or the standard Nginx’s listen directive.

1
restydoc -s listen

screenshot 10

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

screenshot 12

It is extracted from the official Lua 5.1 reference manual.

Or the standard Lua’s C API functions.

1
restydoc -s lua_gc

screenshot 14

Or the LuaJIT’s Lua API extension.

1
restydoc -s ffi.cdef

screenshot 15

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.

screenshot 21

Or a whole Lua module.

1
restydoc resty.redis

screenshot 22

This is the resty.redis library shipped with OpenResty.

screenshot 23

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

screenshot 25

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!