Add built-in documentation. Accessible through /Documentation, with top menu item. Change-Id: I8f6271319a4670fbde832d2362183faded9dc120
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