15 Dec 2012, 07:36

Sphinxでテキストから変幻自在の出力結果比較(HTML,Word,PDF,ePub)

Sphinxの魅力の一つが、ひとつのテキストから様々なフォルダ形式に出力可能な点だ。

今回は以下の形式の出力結果をまとめてみようと思う。

  • HTML
  • Word
  • PDF
  • ePub

HTML出力

まずは基本から。

image

PDF出力

rst2pdfを使ってPDF出力しました。

 

image

Word出力

Sphinx-docxbuilderを利用して、Word出力しました。

image

ePub出力

IMG_0014

15 Dec 2012, 07:21

SphinxのPDF出力をrst2pdfで試す@Windows64bit

SphinxでPDF出力する方法は以下の2つがあるらしい。

  • rst2pdf
  • Latex

以下のページを参考にした。
SphinxでPDFファイル作成 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
今回はWindows環境で、rst2pdfを使う方法を試してみた。

環境

  • Windows 7 64bit
  • Python 2.6
  • Sphinx1.1.3

rst2pdf設計方法

rst2pdfを手に入れる

easy_installに対応しているので、コマンドプロンプトから以下のコマンドを叩きます。

 easy_install rst2pdf

そうすると、すんなりいかないでしょう。

Pythonモジュールである、PILやReportLabをインストールするところで失敗します。

PILの入手@Winodows64bit version

Windows 64bitユーザはPILを以下のサイトから手に入れます。

ReportLabの入手@Winodows64bit version

ReportLabのインストールは注意が必要です。version2.6ではなくて、2.5を入れます。

以下のサイトにありました。

2.6を入れると以下の様なエラーが発生して、PDF作成に失敗しました。

これは、既知障害っぽいです。

http://code.google.com/p/rst2pdf/issues/detail?id=474

$ rst2pdf -s ja –font-path=C:\Windows\Fonts index.rst

Traceback (most recent call last):

File “/usr/bin/rst2pdf”, line 8, in

load_entry_point(‘rst2pdf==0.92’, ‘console_scripts’, ‘rst2pdf’)()

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 1445, in main

section_header_depth=int(options.section_header_depth),

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 183, in __init__

self.loadStyles(stylesheets)

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 276, in loadStyles

def_dpi=self.def_dpi)

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/styles.py”, line 527, in __init__

reportlab.platypus.tables.CellStyle1.fontname=self[‘base’].fontName

AttributeError: ‘module’ object has no attribute ‘CellStyle1’

日本語フォントのインストール

PDF出力をするためには、日本語フォントを追加する必要があります。

以下の2つをそれぞれダウンロードします。

それぞれ、拡張子がttfのファイルをWindowsのフォントフォルダにコピーします。

  • VL-Gothic-Regular.ttf
  • VL-PGothic-Regular.ttf
  • ipag.ttf
  • ipam.ttf
C:\Windows\Fonts

rst2pdfがインストールできたかの確認

試しにSphinxのindex.rstをpdfに変換します。

以下のコマンドを叩いて、index.pdfが生成出来れば成功です。

rst2pdf -s ja --font-path=C:\Windows\Fonts index.rst

Sphinxの設定

各RSTファイルへの実行は成功するようになったので、全てのRSTファイルをまとめて実行できるように、Sphinxの設定ファイルをいじります。

Makefileの修正

まずは、make pdfが実行できるように、Makefileの終わりに以下を追加します。

Makefileの常識で、先頭の空白は必ずタブにします。

pdf:
        $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
        @echo
        @echo "Build finished. The PDF files are in _build/pdf."

conf.pyの修正

conf.pyにrst2pdfを実行する際のオプションを設定します。

extensions = ['rst2pdf.pdfbuilder']

pdf_documents = [
    ('index', u'MyProject', u'My Project', u'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4','ja']

import os
font_dir = os.path.abspath(os.path.join(os.path.split(__file__)[0], os.pardir, 'fonts'))
pdf_font_path = [font_dir, 'C:\WINDOWS\Fonts']

pdf_language = "ja"

フォントの指定

最後にフォントを指定するための設定ファイルを作ります。

ja.jsonという名前で、以下の内容を追記します。

{
  "embeddedFonts" : [
    [
        "VL-Gothic-Regular.ttf",
        "VL-PGothic-Regular.ttf",
        "ipam.ttf",
        "ipag.ttf"
     ]
  ],
  "fontsAlias" : {
    "stdFont": "VL-PGothic-Regular",
    "stdBold": "VL-PGothic-Regular",
    "stdItalic": "VL-PGothic-Regular",
    "stdBoldItalic": "VL-PGothic-Regular",
    "stdMono": "VL-PGothic-Regular",
    "stdMonoBold": "VL-PGothic-Regular",
    "stdSanBold": "VL-PGothic-Regular",
    "stdSansBold": "VL-PGothic-Regular"
  },
  "styles" : [
    ["base" , {
      "wordWrap": "CJK"
    }],
    ["literal" , {
      "wordWrap": "None"
    }]
  ]
}

PDFを生成する

以下のコマンドで、_build/pdf配下にPDFが生成されます。

make pdf

image

10 Dec 2012, 23:37

EclipseにJMockを入れてSecurityExceptionが発生。

EclipseにJMockを入れたところ、java.lang.SecurityExceptionという例外が発生した。

java.lang.SecurityException: class “org.hamcrest.TypeSafeMatcher”‘s signer information does not match signer information of other classes in the same package at java.lang.ClassLoader.checkCerts(ClassLoader.java:943) at java.lang.ClassLoader.preDefineClass(ClassLoader.java:657) at java.lang.ClassLoader.defineClass(ClassLoader.java:785) at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142) at java.net.URLClassLoader.defineClass(URLClassLoader.java:449) at java.net.URLClassLoader.access$100(URLClassLoader.java:71) at java.net.URLClassLoader$1.run(URLClassLoader.java:361) at java.net.URLClassLoader$1.run(URLClassLoader.java:355) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(URLClassLoader.java:354) at java.lang.ClassLoader.loadClass(ClassLoader.java:423) at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308) at java.lang.ClassLoader.loadClass(ClassLoader.java:356) at java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:791) at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142) at java.net.URLClassLoader.defineClass(URLClassLoader.java:449) at java.net.URLClassLoader.access$100(URLClassLoader.java:71) at java.net.URLClassLoader$1.run(URLClassLoader.java:361) at java.net.URLClassLoader$1.run(URLClassLoader.java:355) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(URLClassLoader.java:354) at java.lang.ClassLoader.loadClass(ClassLoader.java:423) at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308) at java.lang.ClassLoader.loadClass(ClassLoader.java:356) at org.jmock.internal.InvocationExpectationBuilder.createExpectationFrom(InvocationExpectationBuilder.java:86) at org.jmock.internal.InvocationToExpectationTranslator.invoke(InvocationToExpectationTranslator.java:19) at org.jmock.internal.FakeObjectMethods.invoke(FakeObjectMethods.java:38) at org.jmock.lib.JavaReflectionImposteriser$1.invoke(JavaReflectionImposteriser.java:33) at $Proxy8.someExternal(Unknown Source) at mock_sampleTest$1.(mock_sampleTest.java:45) at mock_sampleTest.testSome(mock_sampleTest.java:44) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:601) at org.junit.internal.runners.TestMethod.invoke(TestMethod.java:66) at org.jmock.integration.junit4.JMock$1.invoke(JMock.java:37) at org.junit.internal.runners.MethodRoadie.runTestMethod(MethodRoadie.java:105) at org.junit.internal.runners.MethodRoadie$2.run(MethodRoadie.java:86) at org.junit.internal.runners.MethodRoadie.runBeforesThenTestThenAfters(MethodRoadie.java:94) at org.junit.internal.runners.MethodRoadie.runTest(MethodRoadie.java:84) at org.junit.internal.runners.MethodRoadie.run(MethodRoadie.java:49) at org.junit.internal.runners.JUnit4ClassRunner.invokeTestMethod(JUnit4ClassRunner.java:98) at org.junit.internal.runners.JUnit4ClassRunner.runMethods(JUnit4ClassRunner.java:61) at org.junit.internal.runners.JUnit4ClassRunner$1.run(JUnit4ClassRunner.java:54) at org.junit.internal.runners.ClassRoadie.runUnprotected(ClassRoadie.java:34) at org.junit.internal.runners.ClassRoadie.runProtected(ClassRoadie.java:44) at org.junit.internal.runners.JUnit4ClassRunner.run(JUnit4ClassRunner.java:52) at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50) at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38) at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:467) at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:683) at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:390) at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:197)

環境

  • Eclipse 4.2
  • JUnit 4
  • JMock2

原因

EclipseのJUnitプラグインに含まれるHamcrestと、jMockのHamcrestのバージョンが異なっているみたい。

EclipseをダウンロードしてきたときのデフォルトJUnitにJMockを追加したら発生した。

解決方法

このページを参考 :

http://stackoverflow.com/questions/4755442/jmock-dependency-issue

以下の解決方法が提示されている。

  • junit.jarの代わりに、junit-dep.jarを使う
  • Eclipseのビルド・パスで、hamcrest.jarをJUnitライブラリの前ではなく、あとに並び替える。

The solution is simple – make sure that hamcrest.jar is before the JUnit library included by Eclipse in the classpath.

I believe if you look at the “Order and Export” tab in the java build path property (Configure Build Path), you will find that the JUnit jar is above the hamcrest.jar. You can move hamcrest above the JUnit jar here and the problem will go away.

  • 重複しているJUnitのHamcrestを削除。

自分は、Eclipseデフォルトのプラグインを削除して、外部から落としてきたJUnitをビルド・パスに設定し直すことで、解決した。ビルド・パスの設定は、以下のエントリを参照。

JUnitのインストールとEclipseでの使い方まとめ

image

09 Dec 2012, 07:12

SphinxをWindowsに導入していろいろした使い方・カスタマイズまとめ

Sphinx関係の記事をたくさん投稿してきたので、ここらでまとめてみます。

Sphinxとは

Sphinx(スフィンクス)とは、文章を書くためのツール(フレームワーク)

エディタとも、wikiとも分類しがたい、新たな書き方のツール。

Sphinx-Users.jp :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

導入方法はこの記事を参照されたし。

SphinxをWindowsPCにインストールした。

Sphinx導入のメリット

利用すると、以下のことができるようになります。

09 Dec 2012, 06:47

Sphinxからepub形式で出力して、Dropbox経由でiPadから読んでみる

Sphinxは、htmlやPDF以外にも、epub形式への変換をサポートしている。

今日は、epub形式でSphinxドキュメントをビルドして、iPadで電子書籍を読むところまでを試してみた。

ePubとは

ePub形式とは、電子書籍で広く採用されている拡張子の規格。

http://ja.wikipedia.org/wiki/EPUB

Sphinxを利用すると、テキストからepub形式のファイルが一瞬で作成できてしまう!

copy.pyのepubの出版情報を記入する

epub形式での出力のためには、sphinxルートディレクトリにあるcopy.pyにepubの情報を記入してやる必要がある。

そもそも、Sphinxを始めた時(sphinx-quickstart)、epubを有効にしていない場合は、設定する項目すらない。

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:

そんな時は、以下のサイトの下の方に設定情報があるので、それをcopy.pyの一番下にコピペする。(自分はそうした)

copy.pyには以下の情報を記入。

epub_basenameは必須項目。ほかは入れなくても大丈夫っぽい。

epub_basename(必須) epubのファイル名
epub_title epubのタイトル
epub_author epubの作者名
epub_copyright コピーライト

ちなにみに、入力のときは、=u’xxx’な感じで、日本語を使うときにuを入れないとエラーする。uがUTF-8を示す。

# -- Options for Epub output ---------------------------------------------------
epub_basename = 'Shinigami_kai'

# Bibliographic Dublin Core info.
epub_title = u'死神・改'
epub_author = u'神楽家きつね'
#epub_publisher = u'神楽家きつね'
epub_copyright = u'2012 神楽家きつね All right reserved'

make epubでSphinxからepub形式へ変換する

変換元のrst形式ファイルは作成済みであること。

rst形式ファイルからSphinxのmakeコマンドでepub形式へ変換するには、

sphinxのルートディレクトリで以下のコマンドを叩けばよい!(簡単\(^0^))

make epub

すると、./_build/配下にepubディレクトリが作成される。

そのしたに、(copy.pyでいれたepub_basename).epubというファイルがある。

これが、epub形式に変換されたファイルだ。

Droxbox経由でiPhone/iPadからepubファイルを見てみる

epubファイルをDropboxの任意の場所に置いて、iPhone/iPadのDropboxアプリで見てみる。

DropboxDropbox

価格: 0円 iTunesで見る

posted with sticky on 2012.12.9

Dropboxのアプリ自体にepub形式のファイルを閲覧する機能はないので、iOSのデフォルトアプリ、ibookで開くを選択。

skitch

すると、iBookが起動して、電子書籍のように閲覧することができる。
IMG_0014 

参考になったサイト

09 Dec 2012, 04:04

マウスいらず、キーボード操作だけでネット閲覧!Chrome拡張プラグインの『Keyboard Navigation』が心地良い

毎日、会社の通勤時間に席に座ってノートPCをいじることが多いのだけれども、電車の中ではマウスが使えないので、なるべくキー操作で全てを済ませようとする。

それでも、Webページの閲覧はマウスがないと辛かったりする。

ネット上の移動をキー操作でできないか調べてみたところ、
Google Chromeの拡張プラグイン、

『Keyboard Navigation』

がなかなかよかったので、紹介。

Keyboard Navigationをつかえば、リンク先URLに番号指定で移動可能!

Keyboard Navigationを使うと、リンク先URLに番号指定で移動することができる。
インストールはChrome ウエブストアから。

Chrome ウェブストア – Keyboard Navigation

 

Keyboard Navigationの使いかた

つかいかたはとても簡単。
使用したいHPで

”,“(カンマ)

を押すだけ。すると、画面上に番号とアルファベットが現れる。

skitch(3)

番号を選択して、Enterを入れると別のリンク先へ飛ぶことができる。

08 Dec 2012, 12:38

SphinxのRSTファイル編集のためにrst.elをemacsに入れる

せっかく、EmacsでRSTファイルを編集するのだから、Lispを使いたいもの。

というわけで、今日はRSTファイル用のEmacsモード

rst-mode

を試してみる。

rst.elをemacsに入れる

以下のHPをrst.elという名前で保存する。

rst.el

これをload-pathの通ったところに置く。

続いて、以下の行を.emacsに追加。

(自分の場合は~/.emacs.d/init.elファイルに書いた)

;; rst.elを読み込み
(require 'rst)
;; *.rst, *.restファイルをrst-modeでOpen
(setq auto-mode-alist
      (append '(("\\.rst$" . rst-mode)
                ("\\.rest$" . rst-mode)
                ) auto-mode-alist))

これで、キーバインドが使えるようになった。

rst-modeのキーバインド

rst-modeのキーバインドは以下のURLから。

とりあえず、よく使いそうなものを抜粋。

コメントアウト (リージョン指定)M-x comment-region
箇条書き (リージョン指定)C-c,C-b
見出しレベル変更 C-c,C-a,C-a
右にインデント C-c,C-r,
|を入れる C-c,C-d

 

ちなみに、いろんなページに書かれているキーバインドは、自分の環境(Windows Cygwin上のEmacs)では動作しなかった。キーバインドが変わったぽい。

実行すると、下の方に別のコマンドを使ってくださいと説明が出るので、そっちで実行するとよい。もしくは、M-x (関数名)でいける。関数名はこのサイトで調べた。

08 Dec 2012, 11:11

EmacsでSphinxのrstファイルを編集するときの気に食わない白色をなんとかしたメモ

emacsでSphinxの編集をしているとき、rstファイルの見出しが白くなってしまって

読みにくい!(というか、読めない)(¬_¬)

今日はこれをなんとかしようと思う。

Before

skitch(1)

frame-background-mode を有効にする

これを解決するためには、Emacsの frame-background-mode を有効にする。
以下の一行を.emacsに追加。
(自分の場合は~/.emacs.d/init.elファイルに書いた)

(setq frame-background-mode 'dark)

これで、背景が黒色に適した色に変更できる。

after

skitch(2)

参考

frame の色を由緒正しく (?) 設定する for frame-background-mode

08 Dec 2012, 10:08

watchdog(watchmedo)でrst定期監視してsphinxビルド。

今週は、1週間かけて、shinixサイトを立ち上げた。
シェルスクリプトでサーバ公開までを自動化した。
シェルスクリプトがバクっていて、rm -rfでsphinxサイトを完全削除してしまった。

うわ~~~~~ w(◎o◎)w

sphinxでrstファイルを作成したあとに、自動ビルドが実行できたら便利だなと思った。
というわけで、(なんか前置きとつながってないけど)自動ビルドを調べてみた。

2つの方法があるっぽい

  • omake
  • watchdog

今回は、watchdogを試してみた。

watchdogでなにができる?

watchdogとはpythonモジュールの一つ。
この中に含まれる、watchmedoコマンドを使うことで、
ファイルの更新があったときにコマンドを実行できる。

環境

  • Sphinx 1.1.3
  • phthon 2.6
  • Windows 7 64bit

watchdogのインストール

pythonとpython setuptoolはインストールされていることが前提。
(なければこのページを参考にして、インストール)
インストールはコマンドプロンプトからeasy_installを実行する。

easy_install watchdog

watchdogの使い方

watchdogのコマンド watchmodeを利用して更新を監視するには以下のコマンドを叩く。

watchmedo shell-command --patterns="*.rst" --recursive --wait --command="make html"

これで、rstファイルを編集すると、watchmedoコマンドが再帰的に変更されたファイルを検索して、変更を検出したら “make htm”を実行する。

watchmedoコマンドオプション

 

コマンド 説明
-h, –help ヘルプ表示
-c COMMAND,

–command COMMAND
実行したいコマンド
-p PATTERNS,

–pattern PATTERNS,

–patterns PATTERNS

監視したい拡張子を指定
-i IGNORE_PATTERNS,

–ignore-pattern IGNORE_PATTERNS

–ignore-patterns IGNORE_PATTERNS

無視する拡張子
-D,

–ignore-directories
無視するディレクトリ
-R, –recursive 再帰的に監視
–interval TIMEOUT

–timeout TIMEOUT
タイムアウト時間指定
-w, –wait 複数実行禁止
          <p>
            &#160;
          </p>

          <h4>
            参考サイト
          </h4>

          <ul>
            <li>
              <a href="http://tell-k.hatenablog.com/entry/2012/01/04/022229">omakeもmakeも使わずに、Sphinxドキュメントの継続的ビルド &#8211; Study08.net 対シンバシ殲滅用人型機動兵器</a>
            </li>
            <li>
              <a href="http://d.hatena.ne.jp/nullpobug/20120331/1333125058">watchdogモジュールのwatchmedoコマンドが便利</a>
            </li>
          </ul>

08 Dec 2012, 02:24

PSP実践のOSS「The Software Process Dashboard」を評価する。

会社のプロジェクトでは、作業時間計測が流行っている。(というより、強制的)
ツールに縛りはないため、みんなはTaskCoachを利用している。

しかし、ヘビーOutlookerな自分はOutlookカレンダーに集計時間をリアルタイムで出力できるTimeEditionを利用している。

時間計測は生産物とセットで評価しないと意味がないと常日頃思っているので、時間計測とともに管理できるツールはないかなと思った。また、Webでチャートを簡単に公開したいと思った。

PSPとは

PSPとは、プレーステーション・ポータブルの略である。
いや、派手に間違えた、Personal Software Processの略。パーソナルソフト開発作法。
個人のソフトウェア開発における時間管理の方法。CMMIの個人バージョン。

詳しくは以下のリンクを参照。

GTDに心酔している自分は、タスクに対して時間を割り当てることは、面倒なのでしない。
大きな枠組みで、時間を計測したい。
ここでは、PSPを実践するためのオープンソースProcess Dashboardを使ってみる。

Process Dashboardをインストール

The Software Process Dashboard | The Software Process Dashboard Initiative

以下のリンクより、ダウンロード。

インストーラを起動して、聞かれるままにOKを押せばよい。
ちなみに、日本語対応しているのが嬉しい。

Process Dashboardを使ってみる

image

UIはシンプル。JAVAでできている。
ホットキーに対応していないのが(一番)つらいところだ。
基本的なタイムトラッキングの機能は揃っている。

  • 階層でのプロジェクト管理
  • 手動での時間修正
  • タイムログの表示
  • 時間集計結果

などなど。時間集計結果のチャートはWEB画面でも出力することができる。

LOC Counter

LOC というのは Life Of Codeの略で、要はステップ数のこと。
時間とコードのステップ数を対応して管理できるみたい。
Subversionがデフォルトでサポートされている。

しかし、自分の要件としてはドキュメント作成時間やテスト項目も管理したいので、これでは足りない。

image

基本機能は、こんな感じ。
拡張機能を利用するためには、アンケートに登録する必要がある。しかし、会社で利用して、さらにはよければ他人の展開することも考えると、これは障害になるかな。