pgAdmin4 v1.0 Bata 1 を使ってみた
kawa.xxx
kawalog
Sphinx で Markdown を使えるようにする
kawa.xxx
記事内に商品プロモーションを含む場合があります
前回、前々回とエンジニア向けのドキュメントを作る話をしていて、gitbook を使ってみましたが、なんとメンテナンスされていないという自体が発覚しました。最初からちゃんと調べろよという感じですが。。。
そこで Python 界隈でよく使われている Sphinx に狙いを定めました。最初は markdown でないマークアップ言語しか使えないと思っており、敬遠していましたが、プラグインを入れることでMarkdownでもドキュメントがかけるようになっているとのことで改めて調査しました。
今回は Sphinx の環境セットアップとMarkdownでサンプルドキュメントを作るところまでをやってみたいと思います。
目次
環境
- MacOSX
- Homebrew
Sphinx をインストールする
Python は Homebrew を使って pyenv をインストールしてあるものと仮定します。
pip install -U Shinx
クイックスタートでひな形を作る
Sphinx には初期に必要なファイルを自動で生成してくれるツールがあります。
専用に作ったディレクトリの中で、 sphinx-quickstart と打ってみると、設定項目をいくつか聞かれた後に、いくつかのファイルやディレクトリが作成されます。
$ sphinx-quickstart Sphinx 2.2.1 クイックスタートユーティリティへようこそ。 以下の設定値を入力してください（Enter キーのみ押した場合、 かっこで囲まれた値をデフォルト値として受け入れます）。 選択されたルートパス: . Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。 ルートパス内にある "_build" ディレクトリを使うか、 ルートパス内に "source" と "build" ディレクトリを分ける方法です。 > ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。 > プロジェクト名: test > 著者名（複数可）: kawa > プロジェクトのリリース []: If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > プロジェクトの言語 [en]: ja ファイル ./conf.py を作成しています。 ファイル ./index.rst を作成しています。 ファイル ./Makefile を作成しています。 ファイル ./make.bat を作成しています。 終了：初期ディレクトリ構造が作成されました。 マスターファイル ./index.rst を作成して 他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。 make builder "builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。
Markdown 用のプラグインをインストールし、使えるようにする
次に Sphinx で Markdown を使えるようにプラグインを一つインストールします。
pip install recommonmark
インストールが完了したら、先程のquickstart で作った conf.py に以下のように追記します。 Extention 自体は記載があるはずなので、 recommonmark の部分を追記すればOKです。
extensions = [ 'recommonmark' ]
Markdownファイルを Sphinx に認識させるために拡張子と、使うパーサーを同じ設定ファイルに書きます。
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
Recommonmark は table に対応していないようなので sphinx-markdown-tables をインストールします。
pip install sphinx-markdown-tables
Recommonmark と同じく、 extentions に名前を書きます。
Markdown ファイルを作って html で表示してみる
プロジェクトのルートディレクトリにある、 index.rst ファイルは削除してください。このファイルが残っていると、markdown ファイルを指定してもこちらが優先されてしまいます。
今回はサンプルとして以下のようなドキュメントを用意しました。
index.md
# hello sphinx! スフィンクスで書く最初のドキュメントです。
ビルドし、HTMLファイルを生成するのは以下のコマンドです。
$ sphinx-build . out index.md
これで out ディレクトリの中に html ファイルが生成されているので、適当なブラウザで表示してみてください。
次回はPDFファイルに出力できる用にしてみたいと思います。
参考文献
- https://sphinx-users.jp/gettingstarted/index.html
- https://qiita.com/it__ssei/items/2a1205cfd3ac3ee61a57
- https://qiita.com/unhurried/items/f0372688e8a8485718b5
ABOUT ME
都内のIT系企業に勤める会社員。自分の備忘録的なアウトプット用の場所で、ボルダリングやガシェッド、セキュリティ、カメラの話題が中心です。