本教程演示了如何使用OpenResty的restydoc命令行工具快速查找Nginx模块、Nginx配置指令、Lua API函数、Lua C函数、Lua模块等OpenResty文档。restydoc工具最初的灵感来自Perl的perldoc工具。

1
2
which restydoc
rpm -qf `which restydoc`

截图1

restydoc实用程序是与OpenResty本身一起发布的,在基于Yum的系统中,它的名字是openresty-doc。在基于Yum的系统中,软件包的名称是openresty-doc

在基于Debian的系统上,比如Ubuntu 20.04,软件包的名字是openresty-restydoc

1
2
3
4
ssh ubuntu20-pkg

which restydoc
dpkg -S `which restydoc`

截图3

我们可以像这样查找Nginx标准指令 rewrite 的文档。

1
restydoc -s rewrite

请注意-s选项,意思是 “段”。

截图6

它是从Nginx官方文档中提取的。在外壳下,它调用了 less 工具。

我们可以使用空格键切换到下一页。

截图8

我们用q键退出。

截图9

或者标准的Nginx的listen指令。

1
restydoc -s listen

截图10

或者我们的OpenResty的nginx模块指令,比如init_worker_by_lua

1
restydoc -s init_worker_by_lua

标准的Lua函数也可以查到。

1
restydoc -s string.find

截图12

它是从官方的Lua 5.1参考手册中提取的。

或标准的Lua的C API函数。

1
restydoc -s lua_gc

截图14

或者LuaJIT的Lua API扩展。

1
restydoc -s ffi.cdef

截图15

或者OpenResty自己的Lua API扩展。

1
restydoc -s ngx.re.match

上面所有的restydoc命令都指定了-s选项。这是因为显示的文档都是一些较大文档中的部分。

我们可以像查看整个Nginx模块的大型文档一样查看。

1
restydoc ngx_http_rewrite_module

这里我们不指定-s选项。

和预期的一样,文本长了很多。

截图21

或者整个Lua模块。

1
restydoc resty.redis

截图22

这是OpenResty附带的resty.redis库。

截图23

或者指定Lua库名。

1
restydoc lua-resty-lrucache

要查看 restydoc 的所有选项,请使用-h选项。

1
restydoc -h

截图25

今天我想介绍的就这么多。希望你觉得这个工具有用。

如果你喜欢这个视频,请订阅我们的 YouTube 频道B 站频道。谢谢!

关于本文和关联视频

本文和相关联的视频都是完全由我们的 OpenResty Demo 系统从一个极简单的剧本文件自动生成的。

关于作者

章亦春是开源项目 OpenResty® 的创始人,同时也是 OpenResty Inc. 公司的创始人和 CEO。他贡献了许多 Nginx 的第三方模块,相当多 Nginx 和 LuaJIT 核心补丁,并且设计了 OpenResty XRay 等产品。

关注我们

如果您觉得本文有价值,非常欢迎关注我们 OpenResty Inc. 公司的博客网站 。也欢迎扫码关注我们的微信公众号:

我们的微信公众号

翻译

我们提供了英文版原文和中译版(本文) 。我们也欢迎读者提供其他语言的翻译版本,只要是全文翻译不带省略,我们都将会考虑采用,非常感谢!