插件文档

文档是任何Jenkins插件的重要组成部分。必威国际有限公司它包括用户文档(插件页面、更改日志、用户指南等)和贡献者文档(如何贡献、开发人员指南等)。本节提供这些文档类型的概述。

插件页面

插件页面托管在插件的网站.这些页面是使用来自最新插件版本和外部文档页面的元数据自动生成的。外部文档可以从GitHub或必威国际有限公司詹金斯维基

我们建议将文档存储在插件的GitHub存储库中。它允许插件维护者从README页面和Jenkins插件站点提供相同的文档,同时它允许使用文档即代码技术,当文档是存储库的一部分时,因此所有常见的实践都可以应用:必威国际有限公司

  • 拉动请求和评论

  • 与特性并行创建文档

  • 从GitHub Web UI编辑文档,具有预览支持

  • 可以很容易地访问以前插件版本的版本控制和文档

使用GitHub作为文档来源

插件站点可以从根README页面或从插件URL定义的其他位置获取文档(见下面)。支持多种格式:GitHub flavor Markdown, Asciidoc或原始文本。

在GitHub上发布插件文档:

  1. 创建一个README页面,并将插件文档放在那里。该页面将成为登录页面插件的网站

    • 可以在存储库中引入更多的文档页面,并从README链接,插件站点将同时显示绝对和相对链接

    • 图片从页面将显示插件网站以及

  2. 修改你的项目URL以指向GitHub存储库,例如。https://github.com/必威国际有限公司jenkinsci/your-plugin.参见下面的Maven和Gradle指南。

  3. 发布新的插件版本。一旦插件的网站选择发布版本(可能需要几个小时),它还会显示来自GitHub的文档。

文档的例子:

基于GitHub的文档的有效URL格式是

https://github.com/必威国际有限公司jenkinsci/YOUR-PLUGIN

的根目录加载README你的插件主分支中的存储库

https://github.com/必威国际有限公司jenkinsci/YOUR-PLUGIN/tree/REF

加载位于根目录中的README你的插件标签或分支中的存储库裁判

https://github.com/必威国际有限公司jenkinsci/YOUR-PLUGIN/blob/REF/path/to/readme.md

加载由路径指定的Markdown或AsciiDoc文件你的插件存储库的标记或分支裁判

如果你使用git标签发布版本,你可以通过设置URL来确保插件站点加载与上一个版本相关的README快照。https://github.com/必威国际有限公司jenkinsci/ $ {project.artifactId} /树/ $ {project.artifactId} - ${修订}

使用GitHub主题

插件标签是由插件库的维护者分配给插件库的GitHub的话题.匹配的GitHub主题插件标签allowlist显示在插件的网站.开发人员被鼓励向插件标签allowlist当他们检测到列表中的空白时。

我们鼓励插件维护人员将GitHub主题应用到他们维护的插件上。当插件与标签的关系远高于平均水平时,应该给插件分配主题。例如,git插件的标签是gitscm-connections但却没有标签bitbucket都githubgitlab,或gitea.作为另一个例子,配置代码插件允许配置许多插件,但不包括它可以配置的所有插件的标签。

开发者不应该使用那些因为过度使用而失去价值的宽泛标签。例如,添加了一些Pipeline步骤的插件通常不应该被标记管道.插件的管道标签应该是Jenkins Pipeline的重要贡献者。必威国际有限公司

使用Jenk必威国际有限公司ins Wiki作为文档来源

必威国际有限公司詹金斯维基在2019年11月变成只读。在wiki上对插件文档页面的请求现在重定向到插件的网站.看到这个页面为更多的信息。它还包括Wiki的GitHub迁移指南。

从项目文件中引用文档页

你应该链接到你插件的文档,无论是在wiki上还是在其他地方,在你插件的pom.xml,(使用有效的URL格式)是这样的:

<项目>...< url >https://github.com/必威国际有限公司jenkinsci/your-plugin< / url >...> < /项目

如果你用Gradle,您可以在您的build.gradle像这样:

必威国际有限公司jenkinsPlugin {/ /……url =https://github.com/必威国际有限公司jenkinsci/your-plugin/ /……

维护人员信息

中列出了每个插件的维护人员信息插件的网站.它目前来自Maven元数据。

有一个使用的计划repository-permissions-updater,请参阅网站- 658在问题跟踪器中。一旦实施,下面的指导方针将会改变。

在POM中,确保包含开发人员信息,例如:

<项目>...< >的开发人员开发人员> <<标识>exampleauthor< / id ><名称>作者姓名< /名称>< >邮件author@example.com< / >邮件< /开发人员>< / >的开发人员> < /项目

id是你的詹金斯。必威国际有限公司io帐户。的的名字是人类可读的显示名称。这确保了更新中心和相关工具能够正确地显示插件的维护者。建议附上电子邮件地址,这样别人就可以联系你了(会在wiki上的插件信息框中显示),但这是可选的。

更新日志

一旦你发布了第一个版本,你应该在你的插件中添加发布说明。你有很多选择:

  • 使用GitHub版本(可能有帮助释放起草者),将发布页面的链接添加到文档页面(推荐)

  • 在存储库根目录中创建一个CHANGELOG文件(Markdown, Asciidoc),并从文档页面链接它

  • 在文档页面中包含变更日志内容

贡献者的文档

对于开源插件来说,有贡献者指南来吸引更多贡献者是很重要的。GitHub提供了定义指导方针并将其展示给贡献者的标准方法,包括贡献指导方针、行为准则、拉请求模板等。

一些注意事项:

表的内容

在中创建文档的插件AsciiDoc可自动生成表的内容的文档。生成的目录默认包括第2级和第3级标题。通过赋值来请求目录toc变量,并插入对toc变量位于应该在页面中插入目录的位置。

= Your Plugin Name:toc: macro [[Introduction]] == Introduction放置在目录前的介绍性文本。toc:[] [[Other - Heading]] == Other Heading Text描述插件的更多信息,放在目录之后。

看到Git插件作为一个目录的例子。

参考文献