Use the new section title style in Asciidoctor. We previous use the section title style like: Section level 1 =============== Section level 2 --------------- Which have a problem in Asciidoctor that the number of "="s or "-"s must match the number of characters in the header exactly, as a result it's easy to make mistakes while changing the titles. Asciidoctor provides a better style like: = Section level 1 == Section level 2 So we switched to this style. Also fixed a bug in replace_macros.py, which will not cause any problem in the old style. Change-Id: I811dd7238735d98f662767c17086152cd69aea02
diff --git a/Documentation/dev-readme.txt b/Documentation/dev-readme.txt index b8fc327..2b0cda8 100644 --- a/Documentation/dev-readme.txt +++ b/Documentation/dev-readme.txt
@@ -1,13 +1,11 @@ -Gerrit Code Review - Developer Setup -==================================== += Gerrit Code Review - Developer Setup Facebook Buck is needed to compile the code, and an SQL database to house the review metadata. H2 is recommended for development databases, as it requires no external server process. -Getting the Source ------------------- +== Getting the Source Create a new client workspace: @@ -21,15 +19,13 @@ cloned. -Compiling ---------- +== Compiling For details on how to build the source code with Buck, refer to: link:dev-buck.html#build[Building on the command line with Buck]. -Switching between branches --------------------------- +== Switching between branches When switching between branches with `git checkout`, be aware that submodule revisions are not altered. This may result in the wrong @@ -45,8 +41,7 @@ ---- -Configuring Eclipse -------------------- +== Configuring Eclipse To use the Eclipse IDE for development, please see link:dev-eclipse.html[Eclipse Setup]. @@ -55,8 +50,7 @@ refer to: link:dev-buck.html#eclipse[Eclipse integration with Buck]. -Mac OS X --------- +== Mac OS X On Mac OS X ensure "Java For Mac OS X 10.5 Upate 4" (or later) has been installed, and that `JAVA_HOME` is set to @@ -67,8 +61,7 @@ [[init]] -Site Initialization -------------------- +== Site Initialization After compiling (above), run Gerrit's 'init' command to create a testing site for development use: @@ -93,13 +86,11 @@ ---- -Testing -------- +== Testing [[tests]] -Running the Acceptance Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the Acceptance Tests Gerrit has a set of integration tests that test the Gerrit daemon via REST, SSH and the git protocol. @@ -113,8 +104,7 @@ link:dev-buck.html#tests[Running integration tests with Buck]. -Running the Daemon -~~~~~~~~~~~~~~~~~~ +=== Running the Daemon The daemon can be directly launched from the build area, without copying to the test site: @@ -123,8 +113,7 @@ java -jar buck-out/gen/gerrit.war daemon -d ../gerrit_testsite ---- -Running the Daemon with Gerrit Inspector -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the Daemon with Gerrit Inspector link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable environment to inspect and modify internal state of the system. @@ -161,8 +150,7 @@ Care must be taken not to modify internal state of the system when using the Inspector. -Querying the Database -~~~~~~~~~~~~~~~~~~~~~ +=== Querying the Database The embedded H2 database can be queried and updated from the command line. If the daemon is not currently running: @@ -180,8 +168,7 @@ [[debug-javascript]] -Debugging JavaScript -~~~~~~~~~~~~~~~~~~~~ +=== Debugging JavaScript When debugging browser specific issues add `?dbg=1` to the URL so the resulting JavaScript more closely matches the Java sources. The debug @@ -200,8 +187,7 @@ ---- -Release Builds --------------- +== Release Builds To create a release build for a production server, or deployment through the download site: @@ -219,8 +205,7 @@ ---- -Client-Server RPC ------------------ +== Client-Server RPC The client-server RPC implementation is gwtjsonrpc, not the stock RPC system that comes with GWT. This buys us automatic XSRF protection. @@ -231,15 +216,13 @@ extend RemoteJsonService instead of RemoteService. -Why GWT? --------- +== Why GWT? We like it. Plus we can write Java code once and run it both in the browser and on the server side. -External Links --------------- +== External Links Google Web Toolkit: