用maven生成HBase官方指南文档

朴灿烈づ我的快乐病毒、 2021-09-25 16:16 299阅读 0赞

说在前面的话：

1.  因为这是翻译，基于水平有限，可能对原文表达不够清楚。
2.  在Linux调用的命令、打印等内容没有翻译，直接使用原文内容。
3.  原文地址找不到了，只能对原作者zhouhh兄说声抱歉。

我一直有一份HBase官方指南，但是我不知道作者是如何编辑这份指南的资源（通过maven生成的xml、html文件）。作者可以灵活调整章节，而我只能遵守按照章节编号规则。

对于这个问题，我向其中一个作者Stack请教，他告诉我：

> 这份指南是使用[docbook][]进行编写的。我们使用[docbkx-tools][]（它的一个maven插件），将内容转为html。你可以通过指定maven站点（mvn site），或者直接通过调用命令 “mvn -Donepage docbkx:generate-html” 生成这份指南文件（因为docbkx需要包含hbase-default.xml文件，所以可能还需要先调用站点获取）。我们进行两次这个过程，一次生成多页指南文件，一次生成单页指南文件（单页指南文件更容易找到）。

我通过使用maven生成book.html文件

[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

报错了：

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

我把hbase-default.xml文件拷贝到指定目录中：

[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 .

运行正常了：

[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

下面是生成的文件及路径：

[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

以下是原文内容，暂存一下，如果哪一天我的英语阅读能力提升了，还能回来鄙视一下自己：

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/. We then usehttp://code.google.com/p/docbkx-tools/ maven plugin to transform the markupto html. This plugin is run when you specify the site goal as in ‘mvnsite’ or you can call the plugin explicitly to just generate the manual bydoing ‘mvn -Donepage docbkx:generate-html’ (It looks like you have to callsite first because docbkx wants to include a transformedhbase-default.xml…). We do the transform twice, once to generate themultipage manual and then again for the single page manual (the single pageversion is easier to search).

I just generated the book.html using maven

it first report an error:

I copy the hbase-default.xml to the target directory:

then, it runs ok:

below is what generated:

[docbook]: http://www.docbook.org/
[docbkx-tools]: http://code.google.com/p/docbkx-tools/