いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。 Software Design 2016年4月号 Markdownで始めるSphinx MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン Markdownで書けるSphinxの構築 - Qiita しかし、recommonmark を利用しても、ドキュメント構造(toctree)を記述するためには部分的に reStructredText を使う必要がありました。 .. toctree chapter1 chapter2 chapter3 これは、文法を拡張する仕組みを持たない markdown の (commonmark の)構造上、仕方がないのですが、せっかく markdown でドキュメントを書いてい
本エントリは、次のAdvent Calendarのために書かれたものです。 ドキュメンテーション Advent Calendar 2013 （12月15日） 取り扱う内容 株式会社ALBERTのシステム開発部では、ドキュメンテーションツールであるSphinxを積極的に活用しています。 Sphinxの導入、利用そのものは簡易に行うことができるのですが、開発部でチームとして運用するためにはいくつかの困難がありました。 そんな幾重にも張り巡らされた困難を乗り越えて、2013年11月頃から本格的に運用が出来ているなぁ、と実感するに至ったので、今回は2013年の総決算としてその変遷を綴ります。 関連資料 Pythonプロダクトを活用した開発チーム運営 in PyCon APAC 2013 - SlideShare SphinxをMarkdownで使い隊 - SlideShare Sphinxとわたし
Sphinx本の執筆体制について¶ この記事は ドキュメンテーション Advent Calendar 2013 の4日目の記事です。 すでにかなり時間がたってしまっておりますが、2013年9月に Sphinxをはじめよう という電子書籍をO'reilly Japan様から出版させていただきました。 もちろんSphinxで執筆しました。ここでは、その際に分かったtipsなどを共 有したいと思います。 のはずだったのですが、特別なことはなにもなく、普通にSphinxで書くだけで したので、Tipsというものはほぼありませんでした。(Sphinx後のフォント周り などでいろいろ問題があったようですが) そのため、今回はどういう体制で執筆したかについて説明したいと思います。 1. 執筆体制¶ 4人で執筆しました。 基本的に一人一章ずつ、それに加えて付録を適当に割り振って執筆していきま した。 2.
Pythonでは関数、クラス、メソッドで最初に現れた文字列リテラルを__doc__に代入し、あとからその関数の意味について調べることが出来ます。これは便利な機能ではあるのですが、しかしただPythonの対話型コンソール画面やIDE、あるいはPython向けの各種プラグインからしか引用できないとなると、とてももったいない。 そこで、Pythonistaがよくつかう、Sphinxというドキュメントツールを使うと、このDocstringをまとめて一つにしてくれます。そのコマンドがsphinx-apidocです。これの詳しい使い方については、公式ドキュメントを見ていただければと思います。上手くいけば、Sphinxのプロジェクトが立ち上がることでしょう。 さて、テスト駆動をやる上において、watchdogであったり、あるいはsnifferにテストをフックして、ファイルが更新されるたびに、テストを起動
Python Web フレームワーク アドベントカレンダー2010のバトンが回ってきましたので、書いてみます。 Sphinx version 1.1から、WebSupportというものが入りました。これは、sphinxのドキュメントをWebサーバにつなぎ、コメントや変更の提案、投票といった機能を追加してくれます。 これ単体だとWebフレームワークとは言い切れませんが、まあ誤差の範囲ということで許してください。 概要把握: 動作している様子 WebSupport開発者のJacob Masonさんが提供しているデモサイトです。これを見て雰囲気を掴んでください。 http://www.jacobmason.com/demo/contents ちなみにこのソースはbitbucketで公開されています。 必要なライブラリ WebSupportはコメントなどをsqliteのDBに保存しますので、それを
Enter search terms or a module, class or function name.
Sphinx Advent Calendar 2012: 18日目 おひさしぶりのfeizです。久しぶりついでにはてブロに移行してみました。 先日、こんなcookbookを投稿しました。 ドキュメントを部分的に公開/非公開にしてビルドする :: ドキュメンテーションツール スフィンクス Sphinx-users.jp 仕事でお客さん向けのドキュメントを書いてると結構需要のある話なんじゃないかなーと思ってます。 ただ、cookbookには実際の利用例みたいなものをあまり入れられなかったので、この機会に実用例や設計手順をまとめてみようと思います。 前提とするシチュエーション 以下のようなシチュエーションを想定します。 とあるB2BサービスのAPIサーバーを書いている 自社(開発)→サービス元(サービス運用)→エンドユーザー(複数社) サービス元とエンドユーザーと自社内の3ロールにそれぞれドキュ
Sphinx Advent Calendar 2012 - connpass の 15日目のエントリとなります。本日は、pandocというドキュメント変換ツールの紹介です。 Sphinx を使う場合、reSTにてドキュメントを記述しますが、例えばプロジェクト管理にRedmineを導入している場合、Wikiに書きためた文章があるかと思います。RedmineのWikiは textile 記法なので、reSTにうまく変換する方法があったらいいと思いませんか？ そんな textile を reST に変換してくれるツールとして使えそうな pandoc を紹介したいと思います。 pandoc とは pandoc は、ユニバーサルドキュメントコンバータです。 textileだけではなく、入力フォーマットとして、markdown, HTMLなどいろいろあり、出力も reST, markdown はもちろ
で使えるようになる。 あまりCSSをいじる気がなければこれでいいかなと思うが、弄りたい場合にはこっちのやり方のほうがいいかな。 あとで何かで使ってみようっと。
難しそうな気配を感じて二の足を踏んでいたが意外とあっさりだったのでメモ。 1. Sphinxの出力ファイルを単に配置するだけでは_staticなどが無視されて悲しくなるので、github pages に Sphinx で生成したドキュメントを公開する。 - kuma8の日記を参考に、sphinxtogithubをインストールする。(←意外とあっさりポイント1) 2. make cleanしてmake htmlし直して問題ないことを確認。 3. 今回HTMLを生成するためのsphinxのコードは今このリポジトリで管理されているので、この手元のワークツリーを空っぽにしたりとかしたくない。そこでリポジトリ内で同じリポジトリをcloneする。ちなみにいまプロジェクトルートがlearn_languageで、その中のsphinxdocってディレクトリの中にいる。 $ git clone https:/
MoinMoin 2.0のビッグニュースに16個あげられていたんだが気になったものを Sphinx-based docs Sphinxベースのドキュメントになって読みやすい。でもmake pdflatexはこけた Storage Layers: stores, backends, middlewares ストレージにファイルだけではなくsqlalchemyで使えるRDBやKyoto Cabinetなんかも使える。 Tree based transformations これに惹かれた という変換経路をたどるのでフォーマットの変換ができる。つまりwikiのコンテンツを好きなフォーマットで取り出せるので、特にReSTで取り出してSphinxにもっていけるようになるのでデータの再利用がしやすそう。 GUI editor update and different approach ckeditorが
OMakeでSphinxを自動継続ビルドしてみよう
題名通りです。Sphinxっていうドキュメント作成ツールがあって、これがなかなか簡単に作れる、かつ様々なフォーマットの書き出しに対応してるのですごく使いやすい。 Sphinxについて詳しく知りたい方は以下のURLを参照すればいいような気がします。 Pythonって何？という人のためのSphinxインストール入門 しかしSphinxには自動でプロジェクトのMakefileが生成されるので簡単にビルドできるようになっているんですけど、それでもhtmlファイルをrstファイルが変更される度に自動ビルドしてくれたらもっと便利になるのにとか思うのが人の常。 というわけで、前回の記事と絡めて、OMakeでSphinxを自動継続ビルドしてみようというのが今回の記事の目的です。 まずはOMakeのインストールからまず、OMakeっていうのはGNU/BSDのmakeもどきみたいなソフトです。でも「もどき」っ
$pip install sphinxcontrib-blockdiag sphinxcontrib-seqdiag \ sphinxcontrib-nwdiag sphinxjp.themes.s6 sphinxjp.themecore \ sphinxjp.themes.sphinxjp sphinxcontrib-googleanalytics cloud_sptheme gcc-4.2 -fno-strict-aliasing -fno-common -dynamic -DNDEBUG -g -fwrapv -Os -Wall -Wstrict-prototypes -DENABLE_DTRACE -arch i386 -arch ppc -arch x86_64 -pipe -DHAVE_LIBZ -I/System/Library/Frameworks/Tcl.framewor
はじめに こんにちは、Sphinx-Users.jpの賑やかし担当です。最近PHP界隈でも人気の高いドキュメント生成ツールSphinxですが、みなさん楽しいSphinxライフを送っていますでしょうか。さて、Sphinxでドキュメントを作った場合、一番キャッチーなのはHTMLだと思うんですが、そのホスティングはみなさんどうされていますか？ Sphinx-Users.jpにいくつかホスティングの方法を紹介してありますが、今日は割と新しいホスティング方法のReadTheDocsをご紹介します。 ReadTheDocsってなに？ Home | Read the Docs rtfd/readthedocs.org · GitHub ReadTheDocsは2010年のDjango Dashで作成されたコードを元に公開されているサービス/ライブラリです。外部に公開されているSphinxのレポジトリ（G
複数人でドキュメント書いたり修正する場合なんかに、Mercurial で Sphinx のドキュメントソースを管理しているわけですが、毎度毎度、 作業領域を更新してから make html するのが面倒なわけです。 で、例によって id:nullpobug が「mercurial の hook 使えば楽だよ」と言ってたので、 早速マネしてみました。 フックって？ Mercurial のリポジトリで発生するイベントを通知して、指定したアクションを 叩いてくれるトリガです。 フックの一覧 changegroup commit incoming outcoming prechangegroup precommit preoutgoing pretag pretxnchangegroup pretxncommit preupdate tag update 今回の場合は、リポジトリ更新完了後に処理を
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
