为你的插件编写文档

文档是插件的必要组成部分。高质量且带有良好示例的文档有助于你的插件被采用。

你为插件编写的文档将在 Logstash 参考 和 Logstash 版本化插件参考 中生成和发布。

以下章节包含在 Github logstash-plugins 组织中托管的插件的文档编写指南。

文档应位于名为 *docs/index.asciidoc* 的单个文件中。 它属于一个名为 *docs/index.asciidoc* 的单个文件。 插件生成实用程序 会为你创建一个起始文件。

使用可以支持生成 ID 的变量来格式化标题锚点。 这种方法在构建 Logstash 版本化插件参考 时会创建唯一的 ID。 需要唯一的标题 ID，以避免插件的多个版本之间出现重复。

示例

不要像这样硬编码插件标题 ID： [[config_models]]

而是使用变量来定义它

[id="plugins-{type}s-{plugin}-config_models"]
==== Configuration models

如果你硬编码一个 ID，Logstash 版本化插件参考 会在第一次构建时正确构建。 第二次运行文档构建时，该 ID 会被标记为重复，并且构建失败。

正确的链接格式对于将用户引导至你希望他们看到的内容至关重要。 不正确的链接格式或重复的链接可能会破坏文档构建。 我们不要这样做。

使用尖括号来格式化指向同一 asciidoc 文件中的内容的链接。

示例

这个链接

<<plugins-{type}s-{plugin}-config_models>>

指向同一文件中的这个标题

[id="plugins-{type}s-{plugin}-config_models"]
==== Configuration models

对于指向 Logstash 参考指南中其他插件或内容的文档的链接，请使用外部链接语法。

示例

{logstash-ref}/plugins-codecs-multiline.html[Multiline codec plugin]

{logstash-ref}/getting-started-with-logstash.html

如果你没有指定链接文本，则 URL 将用作链接文本。

示例

如果你希望你的链接显示为 https://elastic.ac.cn/guide/en/logstash/current/getting-started-with-logstash.html，请使用此格式

{logstash-ref}/getting-started-with-logstash.html

如果你希望你的链接显示为 Logstash 入门，请使用此格式

{logstash-ref}/getting-started-with-logstash.html[Getting Started with Logstash]

我们对指向数据类型描述的链接（例如 <<boolean,boolean>>）做一个例外，因为它们使用得非常频繁。 我们的转换脚本中有一个清理步骤，可以将链接转换为正确的语法。

我们都喜欢代码示例。 Asciidoc 支持代码块和配置示例。 要包含 Ruby 代码，请使用 asciidoc [source,ruby] 指令。

请注意，井号 (#) 的存在是为了使示例正确呈现。 不要在你的 asciidoc 文件中包含井号。

# [source,ruby]
# -----
# match => {
#  "field1" => "value1"
#  "field2" => "value2"
#  ...
# }
# -----

上面的示例（删除井号后）在文档中呈现如下

match => {
  "field1" => "value1"
  "field2" => "value2"
  ...
}

插件文档在发布到 Logstash 版本化插件参考 和 Logstash 参考 之前，需要经过几个步骤。

这是工作流程的概述

• 请确保你已签署贡献者许可协议 (CLA)，并且拥有所有必要的批准和签字。
• 合并你的插件的拉取请求（包括 index.asciidoc 文件、changelog.md 文件和 gemspec）。
• 等待持续集成构建成功完成。
• 将插件发布到 https://rubygems.org.cn。
• 脚本检测新的或更改的版本，并选取 index.asciidoc 文件以包含在文档构建中。
• 你的新插件的文档已发布在 Logstash 版本化插件参考 中。

我们还没完成。

• 对于每个发行版，我们将新的和更改的文档文件打包到拉取请求中，以添加或更新内容。（如果我们对插件文档进行重大更改或添加新插件，我们有时会在发行版之间打包插件文档。）
• 脚本检测新的或更改的版本，并选取 index.asciidoc 文件以包含在文档构建中。
• 我们创建一个拉取请求，并将新的和更改的内容合并到适当的版本分支中。
• 对于新插件，我们在 Logstash 参考 中添加一个指向插件列表的链接。
• 你的新的（或更改的）插件的文档已发布在 Logstash 参考 中。

当你更新你的插件或文档时，请考虑增加 changelog 和 gemspec（或版本文件）中的版本号。 版本更改会触发文档构建，以选取你的更改以进行发布。

有关更多 asciidoc 格式化技巧，请参阅 https://github.com/elastic/docs#asciidoc-guide 中的优秀参考。

有关贡献技巧和 changelog 指南，请参阅 CONTRIBUTING.md。

有关贡献的一般信息，请参阅 为 Logstash 做贡献。