APIドキュメントをPDF出力

ソースコード中に埋め込んだコメントからAPIドキュメントを生成するという仕組みは、javadocによって普及しました。同様の取り組みがjsdocとしてJavaScriptに対しても行われています。ですが、生成された出力を見て使いにくい読みにくいと思う人もいるでしょう。しかし、この手のツールのアウトプットはあくまでもサンプルという位置づけだと考えられます。何が欲しいのかは要求する本人しかわからないですから。仕組みとサンプルを提供するので、好きなように改良して出力してね、というものなのです。

ここで以下の要求があるものとします。

• JavaScriptのソフトウェアのドキュメントが欲しい。
• WordやExcelで手作業でドキュメントを作成するのは避けたい。
• 納品物として出力したいので、せめてPDFにしたい。
• それらしくかっこよく書式を整えたい。

という要求に対して、１つの方法を考えました。ここではjsdoc-toolkitによりJavaScriptのコメントからPDFを出力します。手順は以下の通りとなります。

• jsdocのテンプレートにより、xmldoclet形式のXMLファイルを出力する
• xmldocletファイルをXSLTエンジンによりXSL-FO形式に変換する
• XSL-FOファイルをApache FOPによりPDFに変換する

以上の手順で、そこそこ見栄えのするドキュメントを生成することができましたので、紹介させていただきます。(続く)

  <target name="init-fop">
    <property name="foDir" value="fo"/>
    <path id="run-classpath">
      <fileset dir="fop-1.1/lib">
        <include name="*.jar"/>
      </fileset>
      <pathelement location="fop-1.1/build/fop.jar"/>
    </path>
    <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop" classpathref="run-classpath"/>
  </target>

  <target name="jsdoc-pdf" depends="init-fop">
      <jsdoctoolkit
          jsdochome="lib/jsdoc-toolkit/"
          template="xmldoc"
          outputdir="dist/"
          includeundocumented="true"
          includeprivate="true">
          <fileset dir=".">
            <include name="sample/jsondriver.js"/>
          </fileset>
      </jsdoctoolkit>
      <xslt
          in="dist/xmldoc.xml" 
          out="dist/xslfo.fo"
          style="lib/jsdoc-toolkit/templates/xmldoc/xslfo.xsl"/>
      <fop format="application/pdf"
           outdir="dist"
           messagelevel="warn"
           relativebase="true"
           throwexceptions="false"
           userconfig="fop-1.1/conf/fop.xconf">
        <fileset file="dist/xslfo.fo"/>
      </fop>
  </target>

1. xmldoc_20140821.zip