SphinxのLaTeXのフォーマットをいじる

ドキュメント作成システムSphinxが便利という話を書きました。PDFを出力する方法は2つあって,rst2pdfという拡張を使う方法とLaTeXのファイルをつくってPDFに変換する方法です。ここでは自動で生成されるTeXのフォーマットを変更する方法について述べます。Sphinxは1.2.2を使ってます。

LaTeXでPDFを作るにはまずTeXを一式インストールしておく必要があります。これはユーザー会のサイトに詳しい説明があります。

SphinxとLaTeXの設定が終わったとして,いざ日本語のドキュメントを作ってみると,ドキュメントクラスにjsarticleを使っていてもかなり個性的なフォーマットになっています。気に入らないので,SphinxのTeXソース自動生成の設定を変更します。(ただし,まだ試行錯誤中なので,完全に自分の好みにするには至ってません)

まずSphinxのPythonのソースコードを見ます。MacPortsでMacにインストールした場合は/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/sphinx/にSphinxのソースコードがあります。他の方法でインストールした場合は適宜探して下さい。

このディレクトリには多くのファイルがあります。 lsで見てみると,

__init__.py config.pyc locale/ setup_command.pyc __init__.pyc directives/ make_mode.py texinputs/ addnodes.py domains/ make_mode.pyc themes/ addnodes.pyc environment.py pycode/ theming.py apidoc.py environment.pyc pygments_styles.py theming.pyc apidoc.pyc errors.py pygments_styles.pyc transforms.py application.py errors.pyc quickstart.py transforms.pyc application.pyc ext/ quickstart.pyc util/ builders/ highlighting.py roles.py versioning.py cmdline.py highlighting.pyc roles.pyc versioning.pyc cmdline.pyc jinja2glue.py search/ websupport/ config.py jinja2glue.pyc setup_command.py writers/

がでます。今回変更するのはconfig.py, quickstart.py, writerのlatex.py, texinputsのsphinx.sty, sphinxhowto.cls, sphinxmanual.clsです。

まず,config.pyです。Sphinxではデフォルトの用紙サイズがletterpaperになっているので,a4paperに変更します。これはconfig.pyの中のlatex関係の設定のところにあります。

– latex_paper_size = (‘letter’, None),

+ latex_paper_size = (‘a4’, None),

latex_paper_sizeの設定を変更します。git diffの様子(-が修正前,+が修正後です。以下同様)
sphinxにはsphinx-quickstartという必要なファイルを一気に作ってくれるコマンドがあります。便利なのですが,LaTeXのreportクラスを使う”manual”がデフォルトになっています。LaTeXのarticle (jsarticle)クラスを使う”howto”をデフォルトにします。これはquickstart.pyにあります。quickstart.py内に自動生成するconf.pyの内容がそのまま書いてあるので,そこのLaTeX関連のところを変更します。

– u’%(author_texescaped_str)s’, ‘manual’),

+ u’%(author_texescaped_str)s’, ‘howto’),

上のように自動生成するタイプを変更します。
次にwriterディレクトリのlatex.pyを変更します。このファイルで,元のreSTファイルからTeXのソースファイルを生成するための設定を行っていると思われます。デフォルトの行間が広すぎ気がするので,行間を狭くするように設定しました。全体の行間指定をどこで行っているのかよくわからないので,とりあえず\baselinestretchのコマンドを挿入するようにしました。\baselinestrechを1以下にすると全体の行間が狭くなります。TeXソースの最初のほうに設定が入るように,BEGIN_DOCを以下のように設定しました。

BEGIN_DOC = r”’

\begin{document}

%(shorthandoff)s

\renewcommand{\baselinestretch}{0.8}

”’

途中にdefault_elementsという設定があるので,とりあえず余計な設定は消しました。ここでもpapersizeとpointsizeがありますが,ここだけ変更しても反映されません。config.pyの修正が必要になります。

default_elements = {

‘papersize’: ‘a4paper’,

‘pointsize’: ’10pt’,

‘classoptions’: ”,

‘extraclassoptions’: ”,

‘inputenc’: ‘\\usepackage[utf8]{inputenc}’,

‘utf8extra’: ‘\\DeclareUnicodeCharacter{00A0}{\\nobreakspace}’,

‘cmappkg’: ‘\\usepackage{cmap}’,

‘fontenc’: ‘\\usepackage[T1]{fontenc}’,

‘babel’: ‘\\usepackage{babel}’,

‘fontpkg’: ”,

‘fncychap’: ”,

‘longtable’: ‘\\usepackage{longtable}’,

‘preamble’: ”,

‘title’: ”,

‘date’: ”,

‘release’: ”,

‘author’: ”,

‘logo’: ”,

‘releasename’: ‘Release’,

‘makeindex’: ‘\\makeindex’,

‘shorthandoff’: ”,

‘maketitle’: ‘\\maketitle’,

‘tableofcontents’: ‘\\tableofcontents’,

‘footer’: ”,

‘printindex’: ‘\\printindex’,

‘transition’: ‘\n\n\\bigskip\\hrule{}\\bigskip\n\n’,

}

TeXのドキュメントクラスにjsarticle, jsbookを使いたいので,以下のようにしました。

if document.settings.docclass == ‘howto’:

docclass = builder.config.latex_docclass.get(‘howto’, ‘jsarticle’)

else:

docclass = builder.config.latex_docclass.get(‘manual’, ‘jsbook’)

Sphinxで自動生成されたLaTeXのソースファイルが参照している,sphinx.sty, sphinxhowto.cls, sphinxmanual.clsを変更します。ドキュメントをhowtoにすると,sphinxhowto.cls,manualにするとsphinxmanual.clsが使われます。とりあえずここではsphinxhowto.clsを使うとします。manualの場合は適宜読み替えて下さい。
ページ番号が表示されるようにpagestyleをplainにします。sphinx.styにあります。

\pagestyle{plain}

最初のページのページスタイルはsphinxhowto.clsで指定していますので,それを修正します。ページスタイルが全体で統一されるように81行目あたりの\thispagestyleをコメントアウト。

%\thispagestyle{empty}

デフォルトだと,howtoでsection, subsection, manualでchapter, sectionにしか番号がふられないので,番号がふられる階層を深くします。sphinxhowto.clsのsecnumdepthを変えます。

% Set some sane defaults for section numbering depth and TOC depth. You can

% reset these counters in your preamble.

%

-\setcounter{secnumdepth}{2}

+\setcounter{secnumdepth}{3}

タイトルと目次を変更します。sphinxhowto.clsを修正します。デフォルトの設定だとタイトル部分が広すぎるので,狭くなるように文字サイズを縮小して,リリース番号を消去しました。仕切りの横罫線も消すようにしました。

% Change the title page to look a bit better, and fit in with the fncychap

% “Bjarne” style a bit better.

%

\renewcommand{\maketitle}{

% \rule{\textwidth}{1pt}

\ifsphinxpdfoutput

\begingroup

% These \defs are required to deal with multi-line authors; it

% changes \\ to ‘, ‘ (comma-space), making it pass muster for

% generating document info in the PDF file.

\def\\{, }

\def\and{and }

\pdfinfo{

/Author (\@author)

/Title (\@title)

}

\endgroup

\fi

\begin{center}

\sphinxlogo%

{\Large \@title} \par

% {\em\large\py@HeaderFamily \py@release\releaseinfo} \par

% \vspace{20pt}

\end{center}

\begin{flushright}

\@date \hspace{3zw} \@author \par

% {\large

% \begin{tabular}[t]{c}

% \@author

% \end{tabular}} \par

%% \vspace{2pt}

\py@authoraddress \par

\end{flushright}

目次の横罫線を消去。

\let\py@OldTableofcontents=\tableofcontents

\renewcommand{\tableofcontents}{

\begingroup

\parskip = 0mm

\py@OldTableofcontents

\endgroup

% \rule{\textwidth}{1pt}

\vspace{12pt}

}

結局のところ,Sphinxが生成するLaTeXのフォーマットの変更はwriterのlatex.py, texinputsのsphinx.sty, sphinxhowto.cls, sphinxmanual.clsの修正で行えます。これらの修正はTeXの知識が必要になってきます。今回書いたことがSphinxユーザーの役に立てば幸いです。

疑問なこともまだあります。情報あれば教えて下さい。

  • languageをjaにすると日本語設定になる。”release”が「リリース」になったり,日付が「年月日」になったりする。この変更をはどこでしているのか?
  • 行間の設定はどこでしているのか?

ドキュメント作成システムSphinxが便利

WWDC直前ですが,ドキュメント作成のお話を。

最近知ったのですが,1つのプレーンテキスト(reST)からPDF, html, ePub, Wordのドキュメントを生成するシステムSphinxが便利そうで,試行錯誤しています。

SphinxはPythonのドキュメント作成のための作られたシステムです。以下のリンクでSphinxのことがよく分かります。

Sphinxユーザー会

ドキュメントを作りたくなってしまう魔法のツールSphinx

Pythonのドキュメントを作れるシステムなので,

  • コードハイライトがきれい。対応する言語も多い。
  • 数式はTeXで処理するのできれい。
  • プレーンテキストで書くので,Gitなどでバージョン管理可能。
  • Python環境があれば,すぐにインストールできる。
  • 関連するドキュメントが日本語化されている。

などいろいろいいところがあります。

reSTはreStructuredTextで,マークアップ言語の1種です。世間ではMarkdownのほうが知られていますが,似たような記法です。=, -, ^などで囲めばタイトルになり,+を頭につけるだけで箇条書きになるので,読みやすい文章がかけます。GithubやQiitaの原稿がMarkdownなので,Markdownを使うことが多いかと思います。その場合はPandocで変換できるので,reSTに変換することができるので,特に問題ないです。

htmlでざっくりかいて,確認して,完成版をPDFに変換するということができます。Wordで作文するのに飽きている人にはぜひおすすめします。

Googleが日本語入力メソッドを公開

Googleが本日日本語入力メソッドの「Google日本語入力」のベータ版を公開しました。

Google日本語入力.tiff

Windows32ビット版とMac版が公開されました。Linux版がないのが残念です。

てなわけで,Windows XPとMacにインストールしてみました。

まずWindows。デフォルトのMS-IMEしか入っていない状況だと,変換候補をサジェストしてくれるのは便利です。ATOKとかが入っていたら状況が違うんでしょうが,そんな高級なものはありません。フリーでこれだけ出てくるならかなりいいデキだと思います。Windowsユーザーで,日本語入力環境にこだわったことのないひとは試してみることをおすすめします。インストールも簡単。GoogleのHPからインストール用ファイルをダウンロードしたら,自動で入っていきます。

次にMac。環境はLeopardのままのMacBookです。OS X 10.5.8です。インストールはdmgファイルをダウンロードしてきて,それを展開。あとはクリックしていくだけでインストールされます。言語環境を開いて,入力メソッドを選べば使えます。

僕は普段ことえりを使ってます。ことえりでも変換候補を教えてくれるので,今まで入力してきた言葉が多い分,Google日本語入力よりは賢いです。でも,半角英数字を入力するときに,英数入力に切り替えないといけない弱点があります。これがGoogle日本語入力だと,かな入力のままで半角英数字が入力できました。ここはことえりより優っている部分だと思います。Google日本語入力を使っていて面白いのは,変な言葉に強いこと。「にちゃ」まで入力して,ちゃんと「2ちゃんねる」が候補に出てきます。個人的に2ちゃんねると書くことはまずないですが,おもしろいです。個人的にうれしいのは「じれい」まで打って「自励振動」が候補になることです。研究の関係で「2ちゃんねる」と入力する100倍近くの頻度で入力してます。

Google日本語入力にしても,使いたくなかったらすぐに言語環境でことえりへ変えられるので,とりあえず使ってみるのがいいかもしれません。

Dropboxで今つかっているファイル達をどこからでも見れるようにする

以前,ファイルの管理方法をどうするかという記事を書きました。それの延長みたいな話です。
過去記事:「ファイルの整理はどうするのが最適なの?」

最近,名古屋から仙台に100MB以上の容量のあるファイルを送ることになりました。このときにオンラインストレージサービスのDropboxのことを考えたんですが,相手にも登録してもらうのは面倒だったので,データを入れたSDカードを郵送しました。

このおかげで久しぶりにDropboxのことを思い出したので,改めてどんなことができるのか調べてみました。
Dropboxへのリンク

分かりやすい解説がありましたので,ご紹介。
「Dropbox徹底解剖 – 一度使ったら手放せなくなる! オンラインストレージサービスの本命」

特徴としては
ーオンライン上にファイルをおくので,ネットワークに接続していれば,どんな端末からでもファイルにアクセス可能
ーWindows, Mac, Linux, iPhoneと各プラットフォーム毎にクライアントアプリが提供されている。クライアントアプリを使うと,特にオンライン上のファイルを使うという意識もなく,ローカルファイルのようにして使えます
ークライアントアプリがインストールされてなくても,Webブラウザーからアクセス可能
ー2GBまでは無料で使え,容量を増やしたければ月10$で50GB,月20$で100GBまで使えます
ーPublicフォルダで誰でも共有,Shareフォルダで特定のユーザーと共有することができます
などがあります。

アプリをインストールするとDropboxフォルダができます。緑の印がついているのは同期が完了したファイルです。
dropbox.tiff

どの端末からもローカルフォルダのように使えるので,自分が今使っているファイルを全部Dropboxにいれることにしました。

これで今使っているファイルだけを集中してみることができます。

しかも「あ,ファイルがない!!」なんてこともないです。USBメモリにファイルをコピーして家に持って帰るということもしてましたが,コピー漏れがあったり,コピー自体忘れたりすることがありました。オンラインストレージなのでコピー忘れなんてこともないです。

Dropboxに使用中のファイルをまとめてつっこむ。

これだけでMacからでもWindowsからでもiPhoneからでも同じようにしてファイルを見ることができます。2GBまでは無料なので,使ってみることをおすすめします。

Gmailアドレスの拡張性

Gmailのアドレスに関して。

WordPressで記事をメールで投稿できるようにする途中で知りました。
参考
「使い捨てのメールアドレス・前編──Gmail、Yahoo」

Gmailのアドレス部分(@より前の部分)に
1.プラス「+」をいれると,それ以降の文字列は無視される。

2.途中でドット「.」をいれても,無視される。


具体的に説明します。このブログではメールを「gadget.mac.blog@gmail.com」で受け付けています。何かありましたらメールください。

1.の「+」のほうから。
@より前に+を付けると,その後の文字列はないものとして処理されます。このアドレスで説明すると「gadget.mac.blog+test@gmail.com」にメールを送信すると,gadget.mac.blog@gmail.comに送信されてきます。(もちろん「+」以降の文字列は半角英数字ならなんでも大丈夫です)このとき送信先アドレスはちゃんと「gadget.mac.blog+test@gmail.com」で表示されます。

Toの部分を見ると,gadget.mac.blog+test@gmail.com宛にメールが送信されているのが分かります。 gmail_address1.tiff

何かWeb上でメールアドレスを登録する必要があるときに,+つきのアドレスを登録すると,後からフィルタリングがしやすくなると思います。

次は2.の「.」の説明。
「.」をいくらいれてもちゃんとメールが届きます。「gadget.mac.blog@gmail.com」でいうと「gadgetmacblog@gmail.com」も「g.a.d.g.e.t.mac.blog@gmail.com」も「gadget.mac.blog@gmail.com」に届きます。

実際送信してみたところ。
gmail_address2.tiff

gmail_address3.tiff

これを知っていると,1つのGmailアカウントを拡張して使えます。Gmailスゲー!!