クリスマスが過ぎてから始まる Sphinx アドベントカレンダーへようこそ (嘘) Sphinx 大型連載第二夜です。 タイトルにある通り、Sphinx のメンテナ活動をして一年が過ぎたので、その話をします。 OSS 開発者のひとつのサンプルケースとして、何かの参考になれば幸いです。 Sphinx のメンテナ活動をはじめました 去年の 12月から Sphinx のメンテナ活動をはじめました。 Python のリリースマネージャ活動が忙しかったからか原作者の Georg の活動が鈍り、 また、その後を継いだ清水川さんも忙しくて身動きが取れなくなっていたことから、 コミット権をもらっていたことだし、パートタイムで手伝うかと思ったことがきっかけでした。 以前からコミット権は持っていたものの、一切メンテナとしての活動をしていなかったので、 徐々にチケットが溜まっていく様子に後ろめたくなったのかもし
reStructuredText Markup Specification Author: David Goodger Contact: docutils-develop@lists.sourceforge.net Revision: 10000 Date: 2024-12-12 Copyright: This document has been placed in the public domain. reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document. These constructs are equally easy to read in raw and processed forms. This document
第6日目 Sphinxドキュメントを編集する その３ 今日のご紹介するのは 表 (テーブル) の書き方です。 ディレクティブについて 今日からディレクティブという命令文のような物を使います。前に ..(ピリオド×2 半角スペース) 、 後に :: (セミコロン×2) を付けます。 例えば csv-table ディレクティブを使う際は .. csv-table:: のように記述します。 表について ちょっと残念ですがSphinxは表があまり得意ではありません それでも表は多用しますので、便利かな？と思われる方法についてご紹介します。 CSVテーブル CSV(カンマ区切り)形式を利用して表を作る事ができます。 csv-table ディレクティブを使用します。 記述例: .. csv-table:: :header-rows: 1 :widths: 2, 6 種別, タイトル サプリメント, グ
sphinxのPDF出力ではまったのでメモ。 環境 Mac OS X 10.6 python2.6(標準でつんでるやつ) Sphinx1.0.8 texlive2011 作業メモ Sphinxのrootディレクトリでmake latexを実行した。 yuito@yuito.local> make latex Markup is unsupported in LaTeX: syntax:: column or row spanning cells are not yet implemented. make: *** [latex] Error 1AAで書いた表が悪さしていたみたいで、探しだして撲滅した。 +---------------------+ |aaa | +========+============+ |bbb |ccc | + +------------+ | |dd | +--
渡辺です。 開発者の間ではgithub式Markdownでドキュメントを書くのが主流となっている昨今ですが、エンドユーザ向けのドキュメントとなると出力フォーマット・版管理・クロスリファレンスなど、機能的にもう少し欲しいところです。しかし、Wordといった専用の文書作成ソフトを使うほどでもないし、表計算ソフトを使うのは論外だと思われます。 そんな要求を満たすツールはSphinxです。今回は、Sphinxを利用してドキュメントを生成し、Jenkinsによる自動ビルドでHTML形式のファイルを作成し、S3へのリリースする手順を解説してみます。Sphinxは静的ファイルを生成するため、S3やCloudFrontと相性良く利用できるソリューションです。 Sphinxとは？ Sphinxは、ドキュメント生成ツールです。SphinxではPythonで採用されているreStructuredText(reS
ここ数日 blockdiag の話が続いていましたが、久しぶりに Sphinx の話に戻ります。 僕は Sphinx を使ってお仕事のドキュメントを書いているので、 ドキュメントのひとつとしてデータベース定義書を書くことがあります。 このデータベース定義書、みなさんはどうやってメンテナンスしていますか? 以前、僕のチームでは Excel で定義書を作っていたのですが、 定義書と実際に稼動しているスキーマが異なることが稀にあり、 混乱が生したり、ちょっとしたトラブルの元になることがありました。*1 よく考えてみると、データベース定義書とスキーマを二重に管理しなくてはならないので、 どこかで同期に失敗すると(更新忘れなど)そこに差ができてしまうのは自明なことです。 一部の企業では Excel から DDL を書きだすようなマクロを持っているそうですが、 差分更新ができないなどでうまくメンテナン
あらすじ Sphinxを導入した時にまとめたreST(reStructuredText)記法をアウトプットしよう。まだリファレンス読み込んでおらず、感覚で使っているところもあるので間違った認識もあるかも…そこは学んだら追記しよう。 参考 Overview — Sphinx v1.0 (hg) documentation reStructuredText 基本的にSphinxのサイトに書いてあることを写経してます。 注意 見出しの文字数より少なくならないように上下囲む、とかテーブルは列・行を合わせるとか結構シビアな書き方が求められるのですが……pre記法にしても揃ってない…！ 見出し系 間違って覚えていたので、見出し系についてはSphinxの見出しについて学びなおし - kk_Atakaの日記を参照。 h1見出し 半角イコールで上下を揃えて囲むとh1と同等。 ================
Sphinx, Python 経緯自分用のメモをまとめるツールとして、wiki のかわりに Sphinx を使い始めたのですが...細かいところで融通が効かず (ﾒﾟ皿ﾟ)ﾌﾝｶﾞｰ となることもしばしば。特に、日本語(非ASCII文字)に対応できていない部分が結構あってフラストレーションがたまる一方です。 必須の拡張機能そんな厄介な問題を解決してくれる拡張機能があるんです。具体的には ファイル名やページ内リンクに英語しか使えない、使わない。 索引で仮名も漢字もみんな Symbols になってしまう。 用語集 (glossary ディレクティブ) で並べ替えが Unicode 符号順しか使えない。 NFD で正規(?)化するので濁音が混じるとかな文字でさえ辞書順にならない。といった問題を解決します。(公式より引用 はじめに ― Sphinx 非ASCII文字対応拡張)Sphinx で日本語
日本語版の古いページ¶ このページは現在使われていません。お手数ですが 入り口 に戻ってください。
Sphinxを使って論文っぽい文章を書くときのtipsをまとめておきます。 追記: この内容は Sphinx逆引き辞典により詳細にして載っています。 用語を書く際はreplaceを使う .. |hoge| replace:: ほげらこう定義しておくと次からは |hoge| とするだけで、ほげらと自動的に展開してくれます。つまり、あとからこの用語名を変えたいな、と思ったときにはこの定義のところだけを変えれば勝手に全部入れ替えてくれる、というわけです。 ただし、複数のrstファイルに分けている場合には使えないので、別のファイル(例えばdefinition.txt)に replace を書いておき、 .. include:: definition.txtと各rstファイルの先頭に書いておきます。この時、.rstではなく.txtなど他の拡張子のファイルに書いていることに注意してください。そうしない
Sphinx makes it easy to create intelligent and beautiful documentation. Here are some of Sphinx’s major features: Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information Hierarchic
第13日目 Sphinxドキュメントを編集する その１０ 昨日は画像やファイルへのリンクについて説明しました。 今日は 索引(インデックス) について説明します。 索引(インデックス) 一般の技術書等には、大抵最後の方に索引が記載されていると思います。Sphinxでもドキュメントに .. index:: ディレクティブを記述する事により索引を作成する事ができます。
昨日までの日記の続きです。 Sphinxでドキュメント生成（Windowsでの始め方） - torutkの日記 Sphinxでドキュメント生成-PDF（Windowsでの始め方） - torutkの日記 Sphinxでドキュメント生成-PDF（Windowsでの始め方）（続） - torutkの日記 プログラミングなどの技術情報を人に伝えるために文書を書くときは、日本語の文章主体だけでは効率よく伝達できないので、図・表、ソースコードを織り交ぜます。 Sphinxは、標準で表組み、ソースコードを文書に織り込むことができますが、肝心の図については直接の手段を持っていません。（整形テキストでキャラクタ文字を使った疑似図くらい） ところが、Sphinxを調べていたところ、簡単に図を描くための拡張機能を作成・紹介しているページをいくつか見かけました。たぐっていくと、拡張機能の（多分）作者のブログに行
テキストで書かれたドキュメントのソースをGitHubで共有してJenkinsでHTMLやPDFをビルドする環境については、@kaorun55さんや@ryuzeeさんが紹介してくださっています。 書籍執筆における、継続的なデリバリー - かおるんダイアリー ReVIEW + Jenkinsでドキュメントを常時ビルドする | Ryuzee.com コマンドラインからDropboxを操作する方法 (+Jenkinsとの連携) | Ryuzee.com 最近、コミュニティのあるプロジェクトで複数人でドキュメンテーションをすることになったので 是非、これらの環境を構築したいと思いました。まず、最初は費用が掛からない方法で、始めたいと思い、やり方を検討した結果、ドキュメンテーションのツールにSphinx、リポジトリにGitHub、ビルドにBuildHiveを利用することにしました。 Sphinx-Us
今回の本は3人で書いたこともあり、前回と比べて執筆環境を大きく変えました。 その中の一つに「最新の原稿を、すぐに電子書籍の形で確認できる」環境があります。 専門的に書くと 「Sphinxのドキュメントを、githubにpushすると、JenkinsがビルドしてePubにしてくれる」 ようにしました。もう少し砕くと 「原稿を、インターネット上で共有している場所に置くと、自動で電子書籍の形にしてくれる」 でしょうか。 具体的には、左のようなテキストが、右のような電子書籍に(自動で)なります。 自動的に生成された電子書籍を確認することで、編集者や著者が最新の原稿の内容を確認できるようになっています。 オーム社やオライリー社でやってる制作システムを自前で構築しました、ということです。 より詳細な構築方法については、反響を見て考えようかと思います(アカウント管理やなんかがちょっと手間になりそうなので
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Sphinx の SmartyPants を無効にする
