在终端上用 restydoc 查看 OpenResty 文档
本教程演示了如何使用 OpenResty 的 restydoc
命令行工具快速查找 Nginx 模块、Nginx配置指令、Lua API函数、Lua C函数、Lua模块等 OpenResty 文档。restydoc
工具最初的灵感来自 Perl 的 perldoc
工具。
1 | which restydoc |
restydoc
实用程序是与 OpenResty 本身一起发布的,在基于 Yum 的系统中,它的名字是 openresty-doc
。在基于 Yum 的系统中,软件包的名称是 openresty-doc
。
在基于 Debian 的系统上,比如 Ubuntu 20.04,软件包的名字是 openresty-restydoc
。
1 | ssh ubuntu20-pkg |
我们可以像这样查找 Nginx 标准指令 rewrite
的文档。
1 | restydoc -s rewrite |
请注意 -s
选项,意思是“段”。
它是从 Nginx 官方文档中提取的。在外壳下,它调用了 less
工具。
我们可以使用空格键切换到下一页。
我们用 q
键退出。
或者标准的 Nginx 的 listen
指令。
1 | restydoc -s listen |
或者我们的 OpenResty 的 nginx 模块指令,比如 init_worker_by_lua
。
1 | restydoc -s init_worker_by_lua |
标准的 Lua 函数也可以查到。
1 | restydoc -s string.find |
它是从官方的 Lua 5.1 参考手册中提取的。
或标准的 Lua 的 C API 函数。
1 | restydoc -s lua_gc |
或者 LuaJIT 的 Lua API 扩展。
1 | restydoc -s ffi.cdef |
或者 OpenResty 自己的 Lua API 扩展。
1 | restydoc -s ngx.re.match |
上面所有的 restydoc
命令都指定了 -s
选项。这是因为显示的文档都是一些较大文档中的部分。
我们可以像查看整个 Nginx 模块的大型文档一样查看。
1 | restydoc ngx_http_rewrite_module |
这里我们不指定 -s
选项。
和预期的一样,文本长了很多。
或者整个 Lua 模块。
1 | restydoc resty.redis |
这是 OpenResty 附带的 resty.redis
库。
或者指定 Lua 库名。
1 | restydoc lua-resty-lrucache |
要查看 restydoc
的所有选项,请使用 -h
选项。
1 | restydoc -h |
今天我想介绍的就这么多。希望你觉得这个工具有用。 如果你喜欢这个教程,请订阅这个博客网站和我们的 YouTube 频道 或 B 站频道。谢谢!
关于本文和关联视频
本文和相关联的视频都是完全由我们的 OpenResty Demo 系统从一个极简单的剧本文件自动生成的。
关于作者
章亦春是开源项目 OpenResty® 的创始人,同时也是 OpenResty Inc. 公司的创始人和 CEO。他贡献了许多 Nginx 的第三方模块,相当多 Nginx 和 LuaJIT 核心补丁,并且设计了 OpenResty XRay 等产品。
关注我们
如果您喜欢本文,欢迎关注我们 OpenResty Inc. 公司的博客网站 。也欢迎扫码关注我们的微信公众号:
翻译
我们提供了英文版原文和中译版(本文) 。我们也欢迎读者提供其他语言的翻译版本,只要是全文翻译不带省略,我们都将会考虑采用,非常感谢!