Merge "Add built-in documentation." into stable-2.11
diff --git a/README.md b/README.md
index 08d468b..b5111b6 100644
--- a/README.md
+++ b/README.md
@@ -14,16 +14,8 @@
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 @@
$ 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 @@
[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}
+
diff --git a/pom.xml b/pom.xml
index d545606..f94f05b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -35,6 +35,7 @@
<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 @@
<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,9 +66,33 @@
</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>
<version>2.5.1</version>
<configuration>
diff --git a/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitInitStep.java b/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitInitStep.java
index 75bb925..2580731 100644
--- a/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitInitStep.java
+++ b/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitInitStep.java
@@ -80,6 +80,8 @@
"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
diff --git a/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitTopMenu.java b/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitTopMenu.java
index 5041708..44d62f8 100644
--- a/src/main/java/com/googlesource/gerrit/plugins/gitblit/GitBlitTopMenu.java
+++ b/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 @@
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 @@
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
diff --git a/src/main/resources/Documentation/index.md b/src/main/resources/Documentation/index.md
new file mode 100644
index 0000000..a3a24eb
--- /dev/null
+++ b/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>
\ No newline at end of file
