Webプログラミングコースを教えています。 あなたが人々に教えるとき、「ブーツのない靴屋」ということわざはあなたに当てはまるべきではありません。あなたは目に見える努力をせずに迅速にすべてをしなければなりません。 教科書は簡単でシンプルで、見栄えがよくなければなりません。
一般に、ドキュメント、チュートリアル、またはイラスト付きのテキストのセットを作成する必要がある場合は、
Python Sphinxが必要
です。ここでは、それをすばやく構成して使用する方法を説明します。
Pythonとツールをインストールする
Windowsプラットフォームでは、Pythonが必要になります。Pythonを宿題に任せます。 Pythonに加えて、配布パッケージとcurl（またはwget）が必要です。 distributeと
pipをダウンロードしてインストールします。
curl http://python-distribute.org/distribute_setup.py | python curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
これで、Sphinx自体をインストールできます。
pip install sphinx
* Ubuntu / Debianでsudoを追加
教科書プロジェクトを作成する
その後、プロジェクト用のフォルダーを作成し、その中で
sphinx-quickstartスクリプトを実行するだけです。 彼はいくつかの質問をします。 これらのうち、私の意見では、2つは異なって答えられなければなりません：
> Separate source and build directories (y/N) [n]: y ( - ) > Create Windows command file? (Y/n) [y]: n ( .bat, - , Linux)
下書きの準備ができました。 次に、index.rstを開いて編集を試みます。
ReStructured Textのマークアップを学習する方法は？ 優れたソフトウェアでは、ドキュメントを読む必要はありません。 Sphinxも例外ではありません。Sphinxが作成したすべてのページに、
「ソースを表示」というリンクがあります。 他の人の情報源を見ると、多くのことを素早く学ぶことができます。 見て、実験してください。
実質的な何かを書いた後、コンソールでHTMLアセンブリを開始します。
make html
_build / htmlフォルダーからindex.htmlページを開き、喜んでください。 静的な検索サイトが用意されています（JavaScriptで）。
車の組み立て
最後に、ファイルの編集を開始したときに、make htmlを実行し、そのたびにブラウザーを更新するのは非常に退屈な作業であることがわかりました。 inotifyパッケージを使用すると、ファイルの変更を監視し、コマンドを実行できます。 infotify-toolsとxdotoolをインストールします。
sudo apt-get install inotify-tools xdotool
更新を監視するスクリプトの最も単純なバージョン。 彼は、htmlと単一ファイルの複数ページのドキュメントのアセンブリを開始し、その後、Chromeの開いているタブでF5ボタンを押します。
inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move | while read file event; do make singlehtml html xdotool search --name Chromium key --window %@ F5 done
しかし、欠点はすぐに明らかになります。更新されたファイルの数、何度も更新され、アセンブリが開始されます。 時間的に近いイベントを1つにグループ化する必要があります。 さまざまなオプションを検索した後、Pythonで独自のスクリプトを作成するのではなく、プロジェクトフォルダーから起動されたシェルスクリプトで対処することにしました。
inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move --format '%w %e %T' --timefmt '%H%M%S' | while read file event tm; do current=$(date +'%H%M%S') delta=`expr $current - $tm` if [ $delta -lt 2 -a $delta -gt -2 ] ; then sleep 1
彼はイベントの時間を自分の順番になった時間と比較します。 イベントが1〜2秒前に発生した場合は、ドキュメントを再度収集する必要があります。 他のシステムがジョブを終了する（たとえば、hg更新が終了する）ために、スクリプトは1秒間スリープします。 ビルドが始まります。 その後、次のイベントが処理され、非常に古いため、スクリプトはそれらをすぐにスキップします。
Makefileに埋め込むこともできます：
.PHONY autobuild autobuild: <>
ドキュメント形式
Sphinxは複数ページのHTMLを実行でき、単一のファイルを作成でき、PDF、電子書籍（EPUB）、および誰かがCHMを作成できます。
PDFを作成するには2つの方法があります。ラテックスをインストールし、1 GBのパッケージを送り出しますが、出力にキャンディがあります。 別のオプションは、新しいPythonパッケージrst2pdfで、すばやく簡単に作成でき、非常にシンプルなPDFを生成します。 彼はスタイルをまともにするために一生懸命働く必要があります。
PDFドキュメントのダウンロード
メインページにPDFをダウンロードするためのリンクを追加しています。これはダウンロード手順です。 PDF自体には表示されないように、ブロックのみがあります。
.. only:: html :download:` PDF <../build/latex/manual.pdf>`.
注：SphinxはHTMLを収集するときに、このファイルを静的フォルダーにコピーします。 したがって、バージョンを一致させるには、最初にPDFを生成し、次にHTMLのみを生成する必要があります。
転記
3つのオプションがあります。 最も簡単な方法は
、プロジェクトを
BitBucketに
アップロードし 、無料のRead The Docsサービスをリポジトリに追加してから、
ReadTheDocsに登録し、
そこでプロジェクトを作成することです。 メインブランチに新しいリビジョンをアップロードすると、RTDはそれらをダウンロードしてドキュメントをやり直します。 したがって、プログラムライブラリのドキュメントに特に対処する必要はありません。ドック文字列を最新に保つのに十分です。
自分用に閉じたサイトを維持したい場合は、パスワードで保護されたシンプルなサイトを作成して、手動で収集できます。 _build / htmlフォルダーのコンテンツをサイトのルートにアップロードするだけで十分です。 これにはrsyncを使用し、Makefileに2行書きました。
.PHONY: sync sync: latexpdf html rsync -ave ssh build/html/ siberiano@hosting:/home/siberiano/webapps/course_manual/ --delete
最初に、ドキュメントはlatexpdf形式で収集され、次にhtml（および「ダウンロード」にPDFが追加されます）、次にrsyncがファイルをホスティングにアップロードし、古いファイルを削除します（オプション--delete）。
見知らぬ人から独立した独自のクローズドシステムが必要な場合は、
ReadTheDocsクローンを実行できます。
美しいデザイン
Sphinxは「テーマ」を使用します。これらは
Jinjaテンプレートと1つのフォルダー内の静的ファイルです。
無料アクセスから収集したいくつかのトピックを投稿しました。 テーマを有効にするには、conf.pyの2行を設定する必要があります。
html_theme = 'armstrong'
結果：
まとめ
Sphinxは、最小限のデータから静的なWebサイトを作成できる非常に強力なツールです。 多くの静的テキストと写真の場合、これが最適なオプションです。 すぐに上げて、非常に迅速に更新できます。 また、ソフトウェアライブラリのドキュメントは、通常、開発者の夢であるあなたの努力なしに、それ自体で組み立てられます！
PS自動文書化の方法の例を追加するのを忘れました。 実際、
設定と
ソースコードはどのプロジェクトでも見ることができ、
sphinx-apidocを知ることも役立ちます。
2012年11月11日の
補遺： GitHubで、RSTとMarkdownを編集するユーザー専用に作成された、SublimeTextの事前に
フォーマットされたテーブルエディターを見つけました。