opendev/gerrit
Code Issues Proposed changes

Allow plugins to provide an 'about' section on their documentation index

Browse Source 
If a plugin provides a documentation file named "about.md|html", its
content will be inserted at the top of the index page above the lists
of documentation and commands.

If both "about.md" and "about.html" exist, only the first one to be
discovered from the JAR file will be used.

Change-Id: Id0de957b4cc5c2763e945310e252b59e27756639
This commit is contained in:
David Pursehouse
2013-07-10 11:38:03 +09:00
parent 611bdde44f
commit 6853b5a996
2 changed files with 41 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
Documentation/dev-plugins.txt
View File

@@ -384,11 +384,11 @@ If a plugin does not register a filter or servlet to handle URLs
`/Documentation/*` or `/static/*`, the core Gerrit server will
automatically export these resources over HTTP from the plugin JAR.
Static resources under `static/` directory in the JAR will be
Static resources under the `static/` directory in the JAR will be
available as `/plugins/helloworld/static/resource`. This prefix is
configurable by setting the `Gerrit-HttpStaticPrefix` attribute.
Documentation files under `Documentation/` directory in the JAR
Documentation files under the `Documentation/` directory in the JAR
will be available as `/plugins/helloworld/Documentation/resource`. This
prefix is configurable by setting the `Gerrit-HttpDocumentationPrefix`
attribute.
@@ -444,9 +444,15 @@ For any discovered HTML (`*.html`) file, Gerrit will use the name
of the file, minus the `*.html` extension, as the link text. Any
hyphens in the file name will be replaced with spaces.
If a discovered file is named `about.md` or `about.html`, its
content will be inserted in an 'About' section at the top of the
auto-generated index page. If both `about.md` and `about.html`
exist, only the first discovered file will be used.
If a discovered file name beings with `cmd-` it will be clustered
into a 'Commands' section of the generated index page. All other
files are clustered under a 'Documentation' section.
into a 'Commands' section of the generated index page.
All other files are clustered under a 'Documentation' section.
Some optional information from the manifest is extracted and
displayed as part of the index page, if present in the manifest:

32
gerrit-httpd/src/main/java/com/google/gerrit/httpd/plugins/HttpPluginServlet.java
View File

@@ -44,8 +44,10 @@ import org.eclipse.jgit.util.RawParseUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
@@ -330,6 +332,7 @@ class HttpPluginServlet extends HttpServlet
ResourceKey cacheKey, HttpServletResponse res) throws IOException {
List<JarEntry> cmds = Lists.newArrayList();
List<JarEntry> docs = Lists.newArrayList();
JarEntry about = null;
Enumeration<JarEntry> entries = jar.entries();
while (entries.hasMoreElements()) {
JarEntry entry = entries.nextElement();
@@ -339,8 +342,13 @@ class HttpPluginServlet extends HttpServlet
&& (name.endsWith(".md")
|| name.endsWith(".html"))
&& 0 < size && size <= SMALL_RESOURCE) {
if (name.substring(prefix.length()).startsWith("cmd-")) {
name = name.substring(prefix.length());
if (name.startsWith("cmd-")) {
cmds.add(entry);
} else if (name.startsWith("about.")) {
if (about == null) {
about = entry;
}
} else {
docs.add(entry);
}
@@ -364,6 +372,28 @@ class HttpPluginServlet extends HttpServlet
md.append("\n");
appendPluginInfoTable(md, jar.getManifest().getMainAttributes());
if (about != null) {
InputStreamReader isr = new InputStreamReader(jar.getInputStream(about));
BufferedReader reader = new BufferedReader(isr);
StringBuilder aboutContent = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
line = line.trim();
if (line.isEmpty()) {
aboutContent.append("\n");
} else {
aboutContent.append(line).append("\n");
}
}
reader.close();
// Only append the About section if there was anything in it
if (aboutContent.toString().trim().length() > 0) {
md.append("## About ##\n");
md.append("\n").append(aboutContent);
}
}
appendEntriesSection(jar, docs, "Documentation", md, prefix, 0);
appendEntriesSection(jar, cmds, "Commands", md, prefix, "cmd-".length());