サイトマップ

APIドキュメントをPDF出力

はじめに

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

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

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

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

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

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

build.xmlサンプル

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

ダウンロード

 
research/1409522371.txt · 最終更新: 2014/09/01 06:59 by Kazuyuki Matsuda
特に明示されていない限り、本サイトの内容は次のライセンスに従います:Copyright(C) 2011 Shorindo, Inc. All Rights Reserved
Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki