ドキュメントとノートホルダーreStructuredTextとSphinx

テキストhttp://qixinglu.com/archives/note_tools_restructuredtext_sphinx
ドキュメントとノートホルダーreStructuredTextとSphinx
28六2011
#作者:投稿/転載
/CC BY-NC-SA 2.5プロトコルを採用
許可、転載は本文のリンクを明記してください
.
本文は七星廬から転載した[原文:ドキュメントとノート利器reStructuredTextとSphinx/著者muzuiget]
ドキュメントやノートの作成については、長い間悩んでいましたが、ネット上のソリューションも大きくプッシュされていました.ScrapBookやZotero、編集が不便で、同期が面倒でした.Google Noteはフォーマットが簡単すぎて、今も更新しないで、Google Docsはまた少し鶏を殺して牛刀を使います.そして不思議に伝わったEvernoteとOnenoteは、私は全然興味がありません.
私のノートの多くは自分で書いたものなので、整理したのは、自分が読めるようにいくつかの文字に簡略化されているだけです.私の要求は、主に純粋なテキスト、ツールのオープンソース、同期とバックアップが可能です.
純粋なテキストを選択して保存するには、メモがきちんと見えるように事前定義されたフォーマットが必要です.エディタには簡単なコードがハイライトされているので、この軽量レベルのタグ言語のウィキペディアページを長い間見ていました.
Wikiもいい案ですが、サーバーを組むには、サーバーを使わなくてもいろいろな構成が避けられません.wikiシステムのフォーマットも違います.またreStructuredTextを検討したところ,読解性が非常に良く,変換できるフォーマットも非常に多いことが分かった.
vimはデフォルトサポートコードがハイライトされ(rst拡張子)、rst2htmlコマンドでhtmlに変換することもできますが、スタイルがあまり理想的ではなく、もっときれいなhtmlジェネレータがあると思います.そこでSphinxというツールを発見し、Pythonの公式ドキュメントソリューションであることを発見しました.
私は最後にこの組み合わせを決定しました.reStructuredTextはタグ言語として、Sphinxは生成ツールとして使用します.
プレビュー
まずreStructuredTextフォーマットのvimでの効果を見てみましょう

html効果を生成するのはpythonスタイルです!

使用
pythonとsphinxをインストールするだけです.python-sphinxというパッケージをインストールすれば、依存を自動的に解決できます.新しいものを追えばpypiでインストールできます(つまりeasy_installコマンドですが、いくつかの依存ライブラリを手動でインストールします).
インストール後、sphinx-quickstartというコマンドがあるはずです.まず空のディレクトリを作成します.このディレクトリにはメモが置かれます.

muzuiget:~$ mkdir note
muzuiget:~$ cd note/
muzuiget:~/note$ sphinx-quickstart

N個の質問をしますが、一般的には4つの場所を記入するだけで、残りは直接車に戻ればいいです.
Project name: Muzuiget Note
Author name(s): muzuiget
Project version: 1
Project release [1]: 1
太くなったのは私が記入したもので、最後の2つのリリース番号は先にバージョン番号と同じでいいです.これは後で変更することができます.そしてこのディレクトリの内容はこうです

muzuiget:~/note$ tree .
.
|-- _build
|-- conf.py
|-- index.rst
|-- make.bat
|-- Makefile
|-- _static
`-- _templates

3 directories, 4 files

テキストエディタでindexを開くことができます.rstというファイルはvimを使うとコードがハイライトされていることに気づきます.しばらくは何も変えずに運転します

muzuiget:~/note$ make html

ブラウザで開く_build/html/index.htmlには、鳥が快適できれいなpythonドキュメントに現れます.
コンテンツの追加
もちろん今は何もありませんindexに向かいますrstはコンテンツを追加すればいいです.reStructuredTextの文法については、reStructuredText、Sphinx、Pythonの簡単なチュートリアルがあります
reStructuredText A ReStructuredText Primer
Sphinx reStructuredText Primer
Python reStructuredText Primer
これらのリンクのhtml自体がreStructuredTextで書かれています.例えば、最初のリンクのソースコードはquickstartとして保存されています.rst、indexに置く.rstの統一ディレクトリの下にあります.次にindexを変更します.rst、行を追加します

.. toctree::
   :maxdepth: 2

   quickstart.rst

「quickstart.rst」の「q」と「:maxdepth:2」のコロンが同じ列にあることに注意し、保存し、再

muzuiget:~/note$ make html

再更新_build/html/index.html、あなたは新しい内容を見て、とても簡単でしょう.htmlのほかsphinxも他のフォーマットをサポートしており、makeを直接実行するとパラメータが表示されます.
ReStructuredText資料
次の問題はreStructuredTextを勉強して規範的なドキュメントとノートを書くことです.reStructuredText公式には迅速な参考があります.参考になる実例はさらに多く、SphinxのドキュメントとPythonのドキュメントは非常に規範的で、ページのそばに「Show Source」リンクがあり、まだ足りない.Sphinxにはリストがある.
実は以前のsphinx-quickstartこのコマンドは主にconf.pyというファイルを作成しました.中にはhtmlや他のフォーマットの構成が出力されています.Sphinxドキュメントを参照して修正することができます.カスタマイズ性はかなり高く、いくつかのテーマも内蔵されています.この方面はまだみんなでゆっくり研究しましょう.
同期
ところで、どうやって同期しますか?もっと考えて、直接ノートフォルダをDropboxに投げてもいいです.簡単です.Bitbucketに私有倉庫を作ってもいいです.