Merge "Add built-in documentation." into stable-2.11

Author: lucamilanesio

README.md

@@ -14,16 +14,8 @@ repository aren't enough as they are missing some specific
 build parameters and constraints (i.e. shaded-jar) that are
 needed for a Gerrit plugin to work properly.
 
-### Wicket
-You need to clone and build a modified version of Wicket that
-is currently published on GitHub under the GerritCodeReview
-organisation: https://github.com/GerritCodeReview/wicket.git
-
-    $ git clone https://github.com/GerritCodeReview/wicket.git
-    $ git checkout wicket-1.4.23-gerrit
-    $ mvn clean install -DskipTests
-
 ### Gitblit
+
 You need to clone Gitblit from GitHub and build it locally
 using the installMaven ANT target.
 
@@ -32,6 +24,7 @@ using the installMaven ANT target.
     $ ant -DresourceFolderPrefix=static installMaven
 
 ### Gitblit plugin
+
 You are ready now to clone and build the Gitblit plugin: the
 Wicket and Giblit dependencies will be taken from your local
 Maven repository.
@@ -46,10 +39,11 @@ the following configuration to your Gerrit config.
     [gitweb]
         type = custom
         linkname = Gitblit
-        url = plugins/
-        revision = gitblit/commit/?r=${project}&h=${commit}
-        project = gitblit/summary/?r=${project}
-        branch = gitblit/log/?r=${project}&h=${branch}
-        filehistory = gitblit/history/?f=${file}&r=${project}&h=${branch}
-        file = gitblit/blob/?r=${project}&h=${commit}&f=${file}
-        roottree = gitblit/tree/?r=${project}&h=${commit}
+        url = plugins/gitblit/
+        revision = commit/?r=${project}&h=${commit}
+        project = summary/?r=${project}
+        branch = log/?r=${project}&h=${branch}
+        filehistory = history/?f=${file}&r=${project}&h=${branch}
+        file = blob/?r=${project}&h=${commit}&f=${file}
+        roottree = tree/?r=${project}&h=${commit}
+

pom.xml

@@ -35,6 +35,7 @@ limitations under the License.
     <Gerrit-Module>com.googlesource.gerrit.plugins.gitblit.GitBlitModule</Gerrit-Module>
     <Gerrit-HttpModule>com.googlesource.gerrit.plugins.gitblit.GitBlitServletModule</Gerrit-HttpModule>
     <wicket.version>1.4.23</wicket.version>
+    <GitBlit-Version>1.7.0-SNAPSHOT</GitBlit-Version>
   </properties>
   <dependencies>
     <dependency>
@@ -46,7 +47,7 @@ limitations under the License.
     <dependency>
       <groupId>com.gitblit</groupId>
       <artifactId>gitblit</artifactId>
-      <version>1.7.0-SNAPSHOT</version>
+      <version>${GitBlit-Version}</version>
     </dependency>
     <dependency>
       <groupId>org.apache.wicket</groupId>
@@ -65,7 +66,31 @@ limitations under the License.
     </dependency>
   </dependencies>
   <build>
+    <resources>
+      <resource>
+        <directory>src/main/resources</directory>
+        <filtering>true</filtering>
+        <includes>
+          <include>**/*.md</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>src/main/resources</directory>
+        <filtering>false</filtering>
+        <excludes>
+          <exclude>**/*.md</exclude>
+        </excludes>
+      </resource>
+    </resources>
     <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>2.7</version>
+        <configuration>
+          <escapeString>\</escapeString>
+        </configuration>
+      </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>

src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitInitStep.java

@@ -80,6 +80,8 @@ private void initGitBlitPluginConfig() {
         "Repositories", true);
     pluginCfg
         .string("\"Activity\" submenu title", "activity", "Activity", true);
+    pluginCfg.string("\"Documentation\" submenu title", "documentation",
+        "Documentation", true);
     String originalValue = pluginCfg.get("search");
     if (originalValue == null) {
       pluginCfg

src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitTopMenu.java

@@ -18,7 +18,6 @@
 import java.util.List;
 
 import com.google.common.collect.Lists;
-import com.google.gerrit.extensions.annotations.Listen;
 import com.google.gerrit.extensions.annotations.PluginCanonicalWebUrl;
 import com.google.gerrit.extensions.annotations.PluginName;
 import com.google.gerrit.extensions.client.GerritTopMenu;
@@ -29,7 +28,6 @@
 import com.google.inject.Inject;
 import com.google.inject.Provider;
 
-@Listen
 public class GitBlitTopMenu implements TopMenu {
 
   // Not configurable to avoid mis-configurations clashing with predefined top
@@ -59,8 +57,11 @@ public GitBlitTopMenu(@PluginName String pluginName,
     MenuItem repositories =
         new MenuItem(cfg.getString("repositories", "Repositories"),
             gitBlitBaseUrl + "repositories/", "");
-    restrictedMenuEntries =
-        new MenuEntry(GITBLIT_TOPMENU_NAME, Arrays.asList(repositories));
+    // GitBlit handles its own "/" url, so Gerrit won't produce any link, not even on the "plugins" page, that would display the documentation.
+    // I've considered simply redirecting "/" to "/Documentation/" since GitBlit's "/" screen is very similar to its "/activity/" screen, but
+    // decided finally to provide an explicit documentation submenu instead.
+    MenuItem documentation = new MenuItem(cfg.getString("documentation", "Documentation"), gitBlitBaseUrl + "Documentation/", "");
+    restrictedMenuEntries = new MenuEntry(GITBLIT_TOPMENU_NAME, Arrays.asList(repositories, documentation));
     List<MenuItem> fullMenuItems = Lists.newArrayList();
     fullMenuItems.add(repositories);
     fullMenuItems.add(new MenuItem(cfg.getString("activity", "Activity"),
@@ -69,6 +70,7 @@ public GitBlitTopMenu(@PluginName String pluginName,
     if (search != null && !search.isEmpty()) {
       fullMenuItems.add(new MenuItem(search, gitBlitBaseUrl + "lucene/", ""));
     }
+    fullMenuItems.add(documentation);
     fullMenuEntries = new MenuEntry(GITBLIT_TOPMENU_NAME, fullMenuItems);
     extraProjectEntries =
         new MenuEntry(GerritTopMenu.PROJECTS, Arrays.asList(new MenuItem(cfg

src/main/resources/Documentation/index.md

@@ -0,0 +1,76 @@
+# GitBlit plugin
+
+This plugin integrates [GitBlit](https://github.com/gitblit/gitblit) _${GitBlit-Version}_ as a repository browser into [Gerrit](https://code.google.com/p/gerrit/),
+with full SSO through Gerrit.
+
+* License: [Apache Public License 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+* [Home page](https://gerrit.googlesource.com/plugins/gitblit/+/refs/heads/master/README.md)
+* Installed plugin version: _${pom.version}_
+
+# Configuration
+
+There are two different configurations: one for Gerrit so it knows how to generate links that will be processed by the plugin, and
+an optional GitBlit configuration for the plugin itself.
+
+## Gerrit configuration
+
+In Gerrit's `gerrit.config`, define the `[gitweb]` section as follows:
+
+	[gitweb]
+	        type = custom
+	        url = plugins/@PLUGIN@/
+	        linkname = browse
+	        project = summary/?r=${project}
+	        revision = commit/?r=${project}&h=${commit}
+	        branch = log/?r=${project}&h=${branch}
+	        filehistory = history/?f=\${file}&r=${project}&h=${branch}
+	        file = blob/?r=${project}&h=${commit}&f=\${file}
+	        roottree = tree/?r=${project}&h=${commit}
+
+This is normally done automatically if you add the plugin and run through `java -jar gerrit.war init -d site_path`, but you can also
+add this manually to Gerrit's config file. The `linkname` can be adapted to your taste.
+
+### Configuring the top menu
+
+This plugin adds a "GitBlit" top menu to Gerrit, and also a new sub-menu item to the "Projects" top menu. Since v2.11 of this plugin, the link
+texts for all sub-menu items can be configured to your taste in a `[plugin "@PLUGIN@"]` section in your `gerrit.config`. If the section is not present,
+or some values in that section are not defined, the plugin uses built-in default texts. The default configuration would correspond to
+
+	[plugin "@PLUGIN@"]
+	        repositories = Repositories
+	        activity = Activity
+	        documentation = Documentation
+	        search =
+	        browse = Browse
+
+The first four are sub-menu items of the "GitBlit" top menu, the last one is a new "browse" sub-menu item in Gerrit's "Projects" menu that is shown
+for Gerrit's "current" project (since v2.11).
+
+The "search" sub-menu item is by default not set and will thus not be shown. Setting it makes only sense if you enable GitBlit indexing on some of
+your projects.
+
+## GitBlit configuration
+
+The plugin includes in the JAR a minimal default configuration to make GitBlit act only as a repository viewer. You can provide your own
+customized [`gitblit.properties`](http://gitblit.com/properties.html) file located in Gerrit's `$GERRIT_SITE/etc` directory.
+The `$GERRIT_SITE/etc/gitblit.properties` takes precedence over the pre-defined configuration settings.
+
+P.S. The following two GitBlit properties are not configurable as changing them would break the plugin functionality:
+
+- git.repositoriesFolder is hardcoded to point to Gerrit repositories directory
+- realm.userService is hardcoded to resolve GitBlit users using Gerrit authentication realm
+
+Additionally the GitBlit ticket service is not available as would not make sense when used in a read only
+repository viewer.
+
+The built-in configuration is archived in the GitBlit source repository. The latest version on master is
+[`gitblit.properties`](https://gerrit.googlesource.com/plugins/gitblit/+/master/src/main/resources/gitblit.properties).
+
+# Issue tracking
+
+Report bugs or make feature requests at the [Gerrit issue tracker](https://code.google.com/p/gerrit/issues/list).
+
+<hr style="color: #C0C0C0; background-color: #C0C0C0; border-color: #C0C0C0; height: 2px;" />
+<div style="float:right;">
+<a href="https://gerrit-review.googlesource.com/#/admin/projects/plugins/gitblit,dashboards" target="_blank">GitBlit plugin ${pom.version}</a>
+</div>