document isn't included in any toctreeという警告が出る¶ どこからも参照されていないrstファイルがあると、sphinxは checking consistency... inclusion-txt.rst:: WARNING: document isn't included in any toctree
document isn't included in any toctreeという警告が出る¶ どこからも参照されていないrstファイルがあると、sphinxは checking consistency... inclusion-txt.rst:: WARNING: document isn't included in any toctree
reStructuredText入門¶ このセクションは、reStructuredText(reST)の考え方や文法についての短いイントロダクションです。Sphinxユーザがドキュメントを作成するために十分な情報を提供します。reSTはシンプルに設計された、控えめなマークアップ言語ですので、理解するのにそれほど時間はかからないでしょう。 段落(パラグラフ)¶ 段落(ref)はreSTドキュメントにおける、もっとも基本的な要素です。段落は1行以上の空行で区切られた、シンプルなテキストの固まりです。 Pythonにおいてインデントが重要な意味を持つのと同様、reSTでもインデントは重要です。同じ段落のすべての行は、インデントを同じ高さにそろえて、左揃えにしなければなりません。 インラインマークアップ¶ 標準のreSTインラインマークアップは極めてシンプルです。 アスタリスク1つ: *テキスト*
ビルド設定ファイル(conf.py)¶ 設定ディレクトリ には必ず conf.py が含まれています。このファイルは “ビルド設定ファイル” と呼ばれていて、Sphinxの入出力の動作をカスタマイズするのに必要な 設定はこのファイルに含まれています。この設定ファイルはPythonのプログラムとして書かれています。 設定ファイルは、ビルド時にPythonコードとして実行される(設定ファイルが含まれる フォルダをカレントディレクトリに設定し、 execfile() を使用して呼び出される)ので、任意の複雑なコードを記述できます。Sphinxが読み込む際には単純にファイルの 中の名前空間に定義されている名前を使うことで、設定を読み込みます。 詳細に説明するにあたっての注意点を列挙します。 特別に指定されていない場合には、設定値は文字列型になります。また、指定されていない場合のデフォルト値は空文字
[buildout] parts = app docutils versions = versions [app] recipe = z3c.recipe.scripts eggs = sphinx sphinxcontrib-docxbuilder sphinxcontrib-blockdiag seqdiag sphinxjp.themes.s6 sphinxjp.themes.htmlslide sphinxjp.themes.sphinxjp interpreter = sphinx-py [docutils] recipe = zc.recipe.egg:scripts eggs = docutils [versions] #lxml = 2.2.8 $ python bootstrap.py -d init $ bin/buildout $ ls bin bin/buildou
buildout を利用して Sphinx 環境を構築する¶ 複数人で Sphinx 文章を扱う場合、ネックになりがちなのが各々のマシンに Sphinx をインストールすることです。特に、Sphinx に加えて外部の Sphinx 拡張を利用している場合は混乱が生じがちです。 ここでは開発環境構築ツールである buildout を利用して、Sphinx 環境の構築を行います。 buildout の導入¶ buildout は以下の 2つのファイルで構成されます。 bootstrap.pybuildout の実行環境を構築するスクリプトです。各マシン上で最初に 1度だけ実行します。 Web 上に公開されているものを wget コマンドで取得します: buildout.cfg環境定義のための設定ファイルです。インストールするパッケージなどを記述することができます。 vi などのテキストエディタ
Rebuild Sphinx documentation on changes, with hot reloading in the browser. Installation sphinx-autobuild is available on PyPI. It can be installed using pip: pip install sphinx-autobuild Usage To build a classical Sphinx documentation set, run: sphinx-autobuild docs docs/_build/html This will start a server at http://127.0.0.1:8000 and start watching for changes in the docs/ directory. When a cha
Update (2015-06-11): There is now a nice installable package to make this even easier, sphinx-autobuild. All you have to do is Update (2013-04-23): livereload now has a ‘shell’ compiler, which simplifies the Guardfile. The post has been modified to reflect this. The big idea I’ve been working with Middleman quite a bit, and really enjoyed their integration with livereload.js. When you save a chang
sphinx-autobuildで再ビルド、ブラウザの再リロードの手間を省いてSphinx文書をサクサク作成Sphinx 概要 本稿では、Sphinxドキュメントを保存するたびに自動的にビルド、ブラウザをリロードしてくれるツールsphinx-autobuildを紹介し、インストール方法や使い方を簡単に説明します。sphinx-autobuildを使うことで、再ビルド、ブラウザの再リロードの手間を省いて、より楽にSphinx文書を作成できます。 はじめに 最近Sphinxを使い始めました。手軽に文章を体系的にまとめることができ、またバージョン管理もしやすく便利に使っています。 しかし、HTML形式などでできあがったドキュメントを見るには、ビルドコマンドを実行しなければならないのが不便です。ブラウザで閲覧している場合、ページの更新も必要です。 そこで、sphinx-autobuildを導入しま
Sphinx でドキュメントを書いているとソースファイル (reST) を HTML に変換するために make html コマンドを実行することが多いと思います。しばらく書いてみると、ソースファイルを変更する度にコマンドを実行して HTML を確認するためにブラウザをリロードして ... という操作は煩雑に思えてきます。 Python LiveReload を使うとファイルの変更を検知してブラウザを自動的にリロードできるようになります。設定スクリプトは Python で記述しますので、Python に関するドキュメントを書いている場合は頭の切り替えが要らない点がメリットと言えます。 バージョンによって設定方法が違っており、各種 API も変わっています。バージョン 2.2.1 からはそろそろ Python 3.x でも使えるようになってきましたので、導入方法をまとめておきます。 dire
Sphinxを使って論文っぽい文章を書くときのtipsをまとめておきます。 追記: この内容は Sphinx逆引き辞典により詳細にして載っています。 用語を書く際はreplaceを使う .. |hoge| replace:: ほげらこう定義しておくと次からは |hoge| とするだけで、ほげらと自動的に展開してくれます。つまり、あとからこの用語名を変えたいな、と思ったときにはこの定義のところだけを変えれば勝手に全部入れ替えてくれる、というわけです。 ただし、複数のrstファイルに分けている場合には使えないので、別のファイル(例えばdefinition.txt)に replace を書いておき、 .. include:: definition.txtと各rstファイルの先頭に書いておきます。この時、.rstではなく.txtなど他の拡張子のファイルに書いていることに注意してください。そうしない
あらすじ Sphinx を導入しようとして Python周りの環境を整えていたら easy_install がやたら失敗したりして困った。 環境 Windows 7 Python 2.7 Python インストール …は、以前入れるだけ入れていた 2.7 があったので割愛。 Sphinx-Users.jp のインストール手順では 2.6 が使われていたので、 2.7 でも大丈夫そう。 環境変数 PATH に以下のパスを追加。 C:\Python27 Pythonのコマンドが含まれるフォルダ C:\Python27\Scripts 次に説明するeasy_installコマンドや、Sphinxのコマンドが格納されるフォルダ easy_install インストール(distribute_setup.py) Ruby でいうところの Bundler のようなもの? setuptools - 清水川
本エントリは、次のAdvent Calendarのために書かれたものです。 ドキュメンテーション Advent Calendar 2013 (12月15日) 取り扱う内容 株式会社ALBERTのシステム開発部では、ドキュメンテーションツールであるSphinxを積極的に活用しています。 Sphinxの導入、利用そのものは簡易に行うことができるのですが、開発部でチームとして運用するためにはいくつかの困難がありました。 そんな幾重にも張り巡らされた困難を乗り越えて、2013年11月頃から本格的に運用が出来ているなぁ、と実感するに至ったので、今回は2013年の総決算としてその変遷を綴ります。 関連資料 Pythonプロダクトを活用した開発チーム運営 in PyCon APAC 2013 - SlideShare SphinxをMarkdownで使い隊 - SlideShare Sphinxとわたし
Markdownで書いたドキュメントをSphinxで閲覧するまで、Gruntを使ってある程度自動化してみたMarkdownPandocSphinxgrunt Markdownで書いたドキュメントをSphinxで閲覧するにはpandocでreStructuredTextに変換し、その後make htmlするのが一般的?な流れだと思うが、都度都度ビルドするのも面倒なのでGruntを使ってタスク化してみました。ついでにgrunt-este-watchとgrunt-contrib-connectでMarkdownファイルが編集されたらビルドとブラウザリロードをするようにしてみました。 Gruntfile.jsは以下のような感じです。 var fs = require("fs") , exec = require('child_process').exec; module.exports = fun
@r_rudi, @shimizukawa, @usaturn の 3人と「Sphinxをはじめよう」を上梓しました *1。 Sphinx 作者の Georg Brandl が来日していたときに話をしたのですが、 どうやら世界初の Sphinx 解説書籍のようです。 オライリーさんの概要説明を引用します。 Officeツールを使用していて、思うようにならずストレスを感じる事はありませんか?あるいは、印刷用の資料を見ている時に、Webブラウザで閲覧しやすいフォーマットになっていて欲しいと思ったりはしませんか? 本書はPythonで標準的なドキュメント作成ツールとして利用されているSphinxの入門書です。Windows、OS X、Linux(Ubuntu)を例に、Sphinxの概要からインストール、基本的な利用法について。またSphinxからLaTeXを経由してPDFを作成したり、EPUBフ
ダウンロード このドキュメントはバージョン1.1 (hg)のためのものです。まだリリースされていません。 Mercurialリポジトリのコードを利用するか、Python Package Indexにあるリリースバージョンを探してください。 疑問? 意見? Googleグループへの参加: もしくは、FreeNodeの#pocooチャンネルへどうぞ 何か気づいたことがあれば、issue trackerを使用して通知することもできます。 Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。 このツールはもともと、新しいPythonのドキュメントの変換のために作られました。Pythonのプロジェクトのためのすばらしい機能を提供してきましたが、現在ではC/C++も既にサポートしています。また、他
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く