2020-02-25

Sphinxを使ってドキュメントを作った

なんで？

友達にTwitter上での取引の方法を教えてくれと言われたので、Sphinxでドキュメントを生成しGitHub Pagesを使用して公開しました。
ブログやふせったーでもよかったのですが、Sphinxを使用してみたかったのです。

Sphinxのインストール

pip install SphinxでOK。使用した時点での最新バージョンは2.4.3。

プロジェクトの作成

sphhinx-quickstartで簡単にドキュメントのテンプレートを作成できます。
いくつか選択肢が出るが大体はデフォルトでいいと思います。プロジェクト名と著者名を入力し、language codeはjaを選択。選んだ言語に翻訳してテキストを生成するらしい。

プロジェクトの編集

プロジェクトを作る — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会 を参考にしてindex.rstの編集をする。索引は不要のため記述していません。
各ページは 早わかり reStructuredText を参考にしながら編集。

HTMLに出力

make htmlで行う。出力先はプロジェクト名/_build/html。

GitHub Pagesで公開

ここが一番難しかった！普通に公開するだけではCSSが適応されずレイアウトが崩れてしまいました。
GitHub Pagesはデフォルトの設定がJekyllでSphinxは非対応っぽく、.nojekyllファイルをGitHub上で作成して対応しました。
この時pushしようとしたらrejectされてしまったのですが、pullをすることでまたpushができるようになりました。
master branchでの公開だとCSSが適応されていなかったので、master branch /docs folder に設定してみたら適応されました。
Git（GitHub）使いこなすまではまだまだ経験が必要だなあ。リファレンスなどとにらめっこしながら仕組みを理解していきたいです。