用maven生成HBase官方指南文档

Posted by abloz on December 26, 2012

from http://abloz.com 2012.12.26

I’m maintain a Chinese copy of HBase official guide, but I don’t know how the author edit the source of the book. The source is xml, and html is generated by maven. So the author can adjust the chapters and sections easily, while I have to follow it’s chapter number hardly.

about this issue, one of the author Stack wrote for me:

The manual is marked up using docbook [http://www.docbook.org/](http://www.docbook.org/).  We then use
[http://code.google.com/p/docbkx-tools/](http://code.google.com/p/docbkx-tools/) maven plugin to transform the markup
to html.  This plugin is run when you specify the site goal as in 'mvn
site' or you can call the plugin explicitly to just generate the manual by
doing 'mvn -Donepage docbkx:generate-html' (It looks like you have to call
site first because docbkx wants to include a transformed
hbase-default.xml...).  We do the transform twice, once to generate the
multipage manual and then again for the single page manual (the single page
version is easier to search).

I just generated the book.html using maven [zhouhh@Hadoop48 hbsrc]$ svn co http://svn.apache.org/repos/asf/hbase/trunk

[zhouhh@Hadoop48 src]$ cd docbkx/ [zhouhh@Hadoop48 docbkx]$ ls book.xml community.xml customization.xsl external_apis.xml ops_mgt.xml preface.xml shell.xml upgrading.xml case_studies.xml configuration.xml developer.xml getting_started.xml performance.xml security.xml troubleshooting.xml zookeeper.xml

[zhouhh@Hadoop48 trunk]$ mvn docbkx:generate-html it first report an error: Recoverable error org.xml.sax.SAXParseException; systemId: file:///home/zhouhh/hbsrc/trunk/src/docbkx/configuration.xml; lineNumber: 702; columnNumber: 52; Include operation failed, reverting to fallback. Resource error reading file as XML (href=’../../target/site/hbase-default.xml’). Reason: /home/zhouhh/hbsrc/trunk/target/site/hbase-default.xml (No such file or directory) Error on line 702 column 52 of file:///home/zhouhh/hbsrc/trunk/src/docbkx/configuration.xml: Error reported by XML parser: An ‘include’ failed, and no ‘fallback’ element was found. [INFO] Reactor Summary: [INFO] [INFO] HBase ……………………………………… FAILURE [22.670s] [INFO] HBase - Common ……………………………… SKIPPED [INFO] HBase - Protocol ……………………………. SKIPPED [INFO] HBase - Client ……………………………… SKIPPED [INFO] HBase - Hadoop Compatibility …………………. SKIPPED [INFO] HBase - Hadoop One Compatibility ……………… SKIPPED [INFO] HBase - Server ……………………………… SKIPPED [INFO] HBase - Hadoop Two Compatibility ……………… SKIPPED [INFO] HBase - Integration Tests ……………………. SKIPPED [INFO] HBase - Examples ……………………………. SKIPPED

I copy the hbase-default.xml to the target directory: [zhouhh@Hadoop48 target]$ pwd /home/zhouhh/hbsrc/trunk/target [zhouhh@Hadoop48 target]$ ls docbkx [zhouhh@Hadoop48 target]$ mkdir site [zhouhh@Hadoop48 target]$ cd site/ [zhouhh@Hadoop48 site]$ cp ../../hbase-server/src/main/resources/hbase-default.xml .

then, it runs ok: [zhouhh@Hadoop48 trunk]$ mvn docbkx:generate-html [INFO] HBase ……………………………………… SUCCESS [13.776s] [INFO] HBase - Common ……………………………… SUCCESS [0.006s] [INFO] HBase - Protocol ……………………………. SUCCESS [0.004s] [INFO] HBase - Client ……………………………… SUCCESS [0.005s] [INFO] HBase - Hadoop Compatibility …………………. SUCCESS [0.003s] [INFO] HBase - Hadoop One Compatibility ……………… SUCCESS [0.007s] [INFO] HBase - Server ……………………………… SUCCESS [0.012s] [INFO] HBase - Hadoop Two Compatibility ……………… SUCCESS [0.005s] [INFO] HBase - Integration Tests ……………………. SUCCESS [0.005s] [INFO] HBase - Examples ……………………………. SUCCESS [0.005s] [INFO] ———————————————————————— [INFO] BUILD SUCCESS

below is what generated: [zhouhh@Hadoop48 docbkx]$ ls book.html configuration.html getting_started.html preface.html troubleshooting.html case_studies.html developer.html ops_mgt.html security.html upgrading.html community.html external_apis.html performance.html shell.html zookeeper.html [zhouhh@Hadoop48 docbkx]$ pwd /home/zhouhh/hbsrc/trunk/target/docbkx