最近Sphinxでよくドキュメントを書くのでメモ。やっぱりある程度巨大なソフトウェアのドキュメントを書く時はWikiじゃなくてSphinxの方が良い気がする。
リンク
他のファイルのセクションにリンクを貼るときには
- そのセクションの前で .. _label: のようにラベル定義
- :ref:`label`でリンクを張る
という感じ。ラベルの名前はドキュメント全体でユニークにする必要がある。
参考
ソースコードのinclude
literalincludeを使う。外部のソースファイルをincludeする時に使った。
.. literalinclude:: ../../src/main/java/net/lampetty/commons/MarkingStopwatch.java
:language: java
:linenos: |
参考
テーブル
通常のテーブルの書き方は非常に面倒なので csv-table 使った。
.. csv-table::
:header: オプション, エイリアス, 必須, 意味
:widths: 30, 15, 8, 80
--url, -r, ◯, DBの接続先URL
--user, -u, ◯, DBの接続ユーザ
--password, -p, ☓, DBの接続パスワード |
みたいな感じ。
参考
ハイフンx2を正しく出力する
Sphinxでは文中に –option みたいに書くと”ー”(全角のハイフン)に置換されてしまう。コマンドラインオプションを表す時に–をよく使うのでどうしようかと思ったら、“–option“ のようにインラインリテラル化すれば大丈夫であった。
参考
前回のエントリからちょいと時間が経ったけど、tomahawk 0.6.0をリリース！
新機能は前回のエントリの通りなんだけど、設定ファイルについては $HOME/.tomahawk.conf の場所に固定ではなく、 -C/–conf オプションで指定できるようにした。これで柔軟に設定ファイルを変えて tomahawk の挙動を変えることができるっす。
次のバージョンでは、やっと重い腰を上げてPython3に対応しようかと思ってる。
すごい久々にtomahawkを更新した。(0.6.0-rc1)
インストール
まだ正式リリース版ではなくpypiには上げていないため、GitHubから直接インストールする感じで。
$ pip install https://github.com/oinume/tomahawk/zipball/0.6.0-rc1 |
新機能
-V/–verify-output
リモートホストで実行したコマンドの出力が全てのホストで同じかどうかを検証するオプション。「なんか1台だけ設定が違くね？」みたいなのが簡単に検証できる。
例えば以下は host1 と host2 の ulimit -a の結果が同一であるかを検証する。
$ tomahawk -V -h host1,host2 'ulimit -a' |
host1とhost2のnginx.confが同一であることを検証したいのであれば、cat するか md5sum すればいい。
$ tomahawk -V -h host1,host2 'cat /etc/nginx/nginx.conf' |
$ tomahawk -V -h host1,host2 'md5sum /etc/nginx/nginx.conf' |
設定ファイル
下記のような $HOME/.tomahawk.conf を用意しておくと、いちいちコマンドラインオプションで指定する手間が省けますよっていう機能。
[tomahawk]
options = --parallel 4
[tomahawk-rsync]
options = --parallel 4 |
上の例だと、tomahawkやtomahawk-rsyncを実行する時に常に –parallel 4 のオプションをつけて実行する。
–output-formatオプションの短縮形-F
-Fで–output-formatが指定できるようになりましたよっと。
まず、DBIなどのライブラリをインストールする。
$ jruby -S gem install dbi dbd-jdbc jdbc-mysql |
こんなスクリプト書いてみる。
require 'dbi'
require 'dbd/Jdbc'
require 'jdbc/mysql'
Jdbc::MySQL.load_driver
DBI.connect(
'DBI:Jdbc:mysql://localhost/test',
'root', 'test',
'driver' => 'com.mysql.jdbc.Driver'
) do |dbh|
puts "Connected"
end |
5行目の “Jdbc::MySQL.load_driver” がないと怒られるので注意。
$ jruby connect.rb
DBI::DatabaseError: java.lang.ClassNotFoundException: com.mysql.jdbc.Driver
connect at /usr/local/jruby-1.7.3/lib/ruby/gems/shared/gems/dbd-jdbc-0.1.6-java/lib/dbd/jdbc/driver.rb:66
connect at /usr/local/jruby-1.7.3/lib/ruby/gems/shared/gems/dbi-0.4.5/lib/dbi/handles/driver.rb:33
connect at /usr/local/jruby-1.7.3/lib/ruby/gems/shared/gems/dbi-0.4.5/lib/dbi.rb:148
(root) at /Users/oinume/Dropbox/code/ruby/connect.rb:6 |
うまくいった場合。
$ jruby connect.rb
Connected |
JavaにはMavenっていう依存ライブラリの管理を行えるすごい便利なツールがあるんだ。RubyでいうところのRubyGems みたいなもんだよ。でもさぁ、RubyGems みたいに自分で作ったライブラリを簡単にアップロードするサーバがないんだよ。えっ、Nexus入れろって？そんなのイチイチ用意してらんないよね。えっ、WebDAV？ムリムリー。本当Javaってなんでもかんでも面倒くさいよね。
そんなあなたに朗報。GitHubリポジトリに特別なブランチを作ってMavenの設定をするだけで、GitHubリポジトリをMavenリポジトリにすることができるんだ。GitHubって本当に開発者に優しいサービスだよねー(-д☆)ｷﾗｯ
※4/3追記：【最新版】Maven Central Repository へのライブラリ登録方法 #mavenに詳しくまとまっているんだけど、Maven Centralリポジトリにartifactを反映するのもそんなに大変ではないので、たぶんこっちの方がいい方法。
流れ
- pom.xmlにいくつか設定を加える
- ~/.m2/settings.xmlにGitHubのアカウント情報を記述
- maven deployする
※このエントリで説明することはHosting a Maven repository on githubと同じ内容なので、英語が得意な人はStackOverflowを見るべし。
pom.xml修正その1
対象のプロジェクト（モジュール）のpom.xmlに以下を追加する。
<distributionManagement>
<repository>
<id>internal.repo</id>
<name>Temporary Staging Repository</name>
<url>file://${project.build.directory}/mvn-repo</url>
</repository>
</distributionManagement> |
試しに下記を実行して、deploy先の mvn-repo ディレクトリにjarが置かれるか確認する。
$ ls -R target/mvn-repo/
net/
target/mvn-repo//net:
lampetty/
target/mvn-repo//net/lampetty:
lampetty-commons/
target/mvn-repo//net/lampetty/lampetty-commons:
1.0.0/ maven-metadata.xml maven-metadata.xml.md5 maven-metadata.xml.sha1
target/mvn-repo//net/lampetty/lampetty-commons/1.0.0:
lampetty-commons-1.0.0-sources.jar
lampetty-commons-1.0.0-sources.jar.md5
lampetty-commons-1.0.0-sources.jar.sha1
lampetty-commons-1.0.0.jar
lampetty-commons-1.0.0.jar.md5
lampetty-commons-1.0.0.jar.sha1
... |
~/.m2/settings.xmlにGitHubのアカウント情報を記述
次に、下記の内容で ~/.m2/settings.xmlファイルを作成する。なお、このファイルのパーミッションは他のユーザから見えないように 700 にしておくこと。
<settings>
<servers>
<server>
<id>github</id>
<username>YOUR-USERNAME</username>
<password>YOUR-PASSWORD</password>
</server>
</servers>
</settings> |
pom.xml修正その2
pom.xmlの properties に下記を追記する。ここで指定する”github”というのは ~/.m2/settings.xml のserverのidと同じものにする。
<properties>
<!-- github server corresponds to entry in ~/.m2/settings.xml -->
<github.global.server>github</github.global.server>
</properties> |
さらにpom.xmlの build の部分に下記を追記する。
<build>
<plugins>
<plugin>
<groupId>com.github.github</groupId>
<artifactId>site-maven-plugin</artifactId>
<version>0.7</version>
<configuration>
<!-- jarファイルをディプロイする時のコミットメッセージ -->
<message>Maven artifacts for ${project.version}</message>
<!-- Jekyllという静的ページを生成するツールは無効 -->
<noJekyll>true</noJekyll>
<!-- 1.で指定したパスと同じものを指定 -->
<outputDirectory>${project.build.directory}/mvn-repo</outputDirectory>
<!-- Mavenリポジトリにするリモートのブランチ名 -->
<branch>refs/heads/mvn-repo</branch>
<includes><include>**/*</include></includes>
<!-- GitHubリポジトリ名 -->
<repositoryName>YOUR-REPOSITORY-NAME</repositoryName>
<!-- GitHubユーザ名 -->
<repositoryOwner>YOUR-GITHUB-USERNAME</repositoryOwner>
</configuration>
<executions>
<!-- run site-maven-plugin's 'site' target as part of the build's normal 'deploy' phase -->
<execution>
<goals>
<goal>site</goal>
</goals>
<phase>deploy</phase>
</execution>
</executions>
</plugin>
</plugins>
</build> |
もう1回mvn deployする。
$ mvn clean deploy
成功すると下記のようなメッセージが表示されて、pom.xmlで指定されたGitHubリポジトリのブランチにartifactであるjarファイルがアップロードされているはず。
...
[INFO] Creating tree with 16 blob entries
[INFO] Creating commit with SHA-1: 2ef011871b0ceb8e29321a2ac9f87648a22c1ff0
[INFO] Creating reference refs/heads/mvn-repo starting at commit 2ef011871b0ceb8e29321a2ac9f87648a22c1ff0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 18.064s
[INFO] Finished at: Tue Apr 02 21:58:07 JST 2013
[INFO] Final Memory: 22M/480M
[INFO] ------------------------------------------------------------------------ |
例えば自分のサンプルプロジェクトである lampetty-commons のmvn-repoブランチにはこんな風にjarがアップロードされている。
ここにアップロードされているjarを使うには、通常のMavenリポジトリと同様に、使いたいプロジェクトのpom.xmlに下記のように記述すればいい。
<repository>
<id>lampetty-commons-github</id>
<url>https://raw.github.com/oinume/lampetty-commons/mvn-repo/</url>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
</repository> |
その他TIPS
なお、deploy先のGitHubのリポジトリやブランチは自由に選べるので、対象のプロジェクトのmvn-repoブランチ以外にもdeployが可能だ。複数のJavaプロジェクトを持っているのであれば、artifact(jar)をdeployする専用のGitHubリポジトリを作成し、そこに集約しても良いだろう。例えば自分は maven-repo-lampetty.net というdeploy専用のGitHubリポジトリを作っている。
とにかくこれでいちいちNexusやらWebDAVサーバを用意する必要がなくなった。GitHub<ﾉ丶｀Д´>ﾉ ﾏﾝｾｰ
Gitポケットリファレンス
著者／訳者：岡本 隆史 武田 健太郎 相良 幸範
出版社：技術評論社( 2012-07-10 )
単行本（ソフトカバー） ( 272 ページ )
最近のコメント