sphinxで文章を書くためのテンプレートです。

Read the Docを利用しています。

sudo apt install pandoc
git clone [email protected]:m0hashi/sphinx-template.git your-project-dir
cd your-project-dir
virtualenv -p python3.7 .venv 
source .venv/bin/activate
pip install -r requirements.txt

下記コマンドの実行でsourceディレクトリ以下に配置されたリソースがビルドされ、 docs/htmlフォルダ配下にビルド成果物が配置されます。

デフォルトでは docs/index.htmlがドキュメントのルートとなります。

# your-project-dir
source .venv/bin/activate
make build

sphinx-autobuildモジュールを利用すると、ファイル変更後に自動的にビルドをすることができます。

このテンプレートでは下記コマンドで実行可能です。

make preview

このコマンドは自動ビルド後のドキュメントをローカルにWebサーバを立ててホストします。

ブラウザから下記URLにアクセスして生成されたドキュメントを見ることができます。

http://localhost:8000

作成したドキュメントは Github Pagesで公開することができます。

このテンプレートのサンプルも下記GighubPagesでホストされています。

masterブランチの/docsを公開する手順を記載します。/docs直下にindex.htmlを始めとするドキュメントが配置されている必要があります。

1. レポジトリのSettingsのタブを選択

   

2. GitHub PagesのセクションのSourceで、master /branch/docsを選択

   

3. 成功するとホストしたGitHub PagesのURLが表示されます。

   

このテンプレートを作成する際に、下記サイトを参考にしました。

• SphinxとGitHub Pagesで技術ノートを公開しよう！