opendev/gerrit
Code Issues Proposed changes

Add more details of what a plugin's documentation contains

Browse Source 
Make more explicit the suggested content of Gerrit plugins'
documentation, so that they can become more discoverable
in a uniform way from a simple code browsing on Gitiles or GitHub.

Change-Id: Ic095086ff4c25b0639492233fce94cfca346e329
This commit is contained in:
Luca Milanesio
2020-12-29 14:29:03 +00:00
parent 452161f6c5
commit a3d41da599
1 changed files with 26 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Documentation/dev-plugins.txt
View File

@@ -2470,6 +2470,32 @@ from Markdown to HTML.
Macros that start with `\` such as `\@KEEP@` will render as `@KEEP@`
even if there is an expansion for `KEEP` in the future.
Documentation should typically contain the following content:
[width="40%",options="header"]
|===================================================
|File | Content
|README.md | Home page of the plugin when browsing its source code on Git
|LICENSE | Open-source license
|resources/Documentation/about.md | Overview of the plugin and its purpose
|resources/Documentation/config.md | Plugin configuration settings and sample configs
|resources/Documentation/build.md | How to build the plugin
|resources/Documentation/cmd-<command>.md | SSH commands
|resources/Documentation/rest-api-<api>.md | REST API
|resources/Documentation/servlet-<servlet>.md | HTTP Servlets
|===================================================
The documentation under resources/Documentation may contain macro that
will be included and expanded by Gerrit once the plugin is loaded.
The files in the root directory are not included in the plugin package
and must not have any macro for expansion. It may also collect
additional information that would make the plugin more discoverable, such as
a more user-friendly description of its use-cases.
The documentation can also include images that can help understanding more
visually how the plugin can interact with the other Gerrit components.
[[auto-index]]
=== Automatic Index