Sphinxの立ち上げ（github＋Netlify利用）#

Last Updated on 2021-08-13

Sphinxを導入し、github/netlify に連携することで簡単に管理できる自前のサイトを構築したので手順をまとめました。

環境について#

Last Updated on 2021-08-14

本記事執筆時点の作業環境。

OS#

Windows10 1909

Python#

3.9

cmd:

python

とすれば、Microsoft Storeからインストールできます。

edtor#

VSCODE 1.50.1

cmd:

code

とすれば、Microsoft Storeからインストールできます。

Python環境の準備#

Last Updated on 2021-08-22

Python仮想環境準備#

Pythonは事前にインストールしておく。今回は、Python環境をキレイに保つために仮想環境で分離。 poetry を利用しました。

インストール手順

ヒント

pip install poetry は推奨手順ではないので注意

venv環境を独立するためのconfig確認・設定:

poetry config --list
poetry config virtualenvs.in-project true

pyproject.tomlの作成:

poetry init

仮想環境の作成:

poetry install

.venvフォルダが作成され、以後、poetry add コマンドでパッケージを追加できます。

Pythonコードも触るかもしれないので下記を念のため追加

poetry add --dev flake8 autopep8 pylint

Sphinx#

Last Updated on 2021-08-22

Sphinx初期整備#

Sphinxパッケージ追加:

poetry add --dev sphinx

Sphinx初期化する。フォルダターゲットはdocsとした:

portry run sphinx-quickstart docs

docsが初期化されているのでビルドしてみる。

poetry run sphinx-build docs docs/_build/ja

docs/_build/ja/index.html [1] を開くとビルド結果を確認できる

sphinx-autobuildによる効率化#

sphinx-autobuildを利用すると、ビルドとブラウザ確認を効率化できます

sphinx-autobuild追加:

poetry add --dev sphinx-autobuild

以降、下記コマンドを一度実行すれば、http://127.0.0.1:8000 でページ確認でき、自動ビルド・自動リロードされる。

poerty run sphinx-autobuild docs docs/_build/ja

sphinx-autobuild起動の効率化#

起動効率化の方針#

2019年に向けてPythonのモダンな開発環境について考えるという記事を参考に実行コマンドを効率化する:

poetry run doc //NG

該当記事のコマンドでの実現は失敗した。理由はpoetryで指定できる[tool.poetry.scripts]は引数指定ができないためである。 [2]

そこで代替パッケージとして poethepoet を活用する:

poetry run poe doc

暫定パッケージを使うことを以外は 2019年に向けてPythonのモダンな開発環境について考えると同一方針。詳細はURLを参照してください。

poethepoetを追加:

poetry add --dev poethepoet

setup.pyの整備#

setup.pyを整備します。

setup.py#

  import os
  import subprocess
  from setuptools import setup, Command


  class SimpleCommand(Command):
      user_options = []

      def initialize_options(self):
          pass

      def finalize_options(self):
          pass


  class DocCommand(SimpleCommand):
      def run(self):
          subprocess.call(["sphinx-autobuild", "docs", "docs/_build/ja"])


  setup(
      cmdclass={
          "doc": DocCommand,
      },
  )

下記コマンドでsetup.pyのコードが実行できる:

poetry run setup.py doc

pyproject.tomlの整備#

pyproject.toml#

[tool.poe.tasks]
  doc = "python setup.py doc"

この作業の結果、次のコマンドでsphinx-autobuildが起動するようになります:

poetry run poe doc

テーマ#

テーマは pydata-sphinx-theme を採用。 * conf.pyで下記対応可能

github、twitterへのリンク

navバーの設定

Google Analyticsの設定

bootstrap4対応
Pandas、NumPy、など主要パッケージで採用

pydata-sphinx-themeのインストール:

poetry add --dev pydata-sphinx-theme

conf.pyの整備:

html_theme = "pydata_sphinx_theme"

その他、詳細は pydata-sphinx-theme を参照

githubとの連携#

Last Updated on 2021-04-17

リポジトリを作成してコミットする。

github準備#

アカウント取得
リポジトリ作成：netlify連携のためPublicで作成
ソースを反映：git initからpushまでのガイドがgithubサイトにあり

githubへssh通信する#

コマンドラインから対応できるようにする設定方法

鍵の生成#

生成コマンド:

ssh-keygen -t rsa

.ssh/id_rsa（秘密鍵）/.ssh/id_rsa.pub（公開鍵）が生成される

公開鍵をクリップボードへ#

win:

clip < ~/.ssh/id_rsa.pub

mac:

pbcopy < ~/.ssh/id_rsa.pub

githubへ登録#

「Add SSH Key」というメニューから、クリップボードの内容を貼り付け

githubの.ssh/config#

~/.ssh/config:

Host my.github.com
    HostName github.com
    User git
    Port  22
    Hostname  github
    IdentityFile  ~/.ssh/id_rsa
    TCPKeepAlive    yes
    IdentitiesOnly     yes

github接続確認#

確認コマンド:

ssh -T git@my.github.com

(参考)gitlabの場合#

netlifyはgitlabも対応している。gitlabの場合のssh接続確認方法。

gitlabの.ssh/config#

~/.ssh/config:

Host my.gitlab.com
    HostName   gitlab.com
    User  git
    Port    22
    IdentityFile   ~/.ssh/config/id_rsa
    TCPKeepAlive  yes
    IdentitiesOnly    yes

gitlab続確認#

確認コマンド:

ssh -T git@my.gitlab.com

netlify連携#

Last Updated on 2021-04-17

netlifyは、githubリポジトリ連携してnetlify上の仮想マシンにデプロイしサイト公開を可能とする。

netlify連携準備#

bulid定義#

指定したリポジトリにあるnetlify.tomlを読み込んでビルドする仕様となっている。

netlify.toml#

[build]
  publish = "docs/_build/ja"
  command = "sphinx-build docs/ docs/_build/ja"

publishは公開するフォルダ、commandがビルド時に使われるコマンドの意味である。

pythonバージョン#

netlifyでデフォルトで立ち上がる仮想環境はUbuntu 16.04（2020年11月現在）です。Pythonバージョンは2.7がデフォルトのため変更する必要があります。バージョンを指定するには、rutime.txtというファイルを用意しバージョン番号を記載します。

runtime.txt#

13.7

なお、Pythonは、2.7、3.5と3.7を選択できます。これ以外のバージョンは指定してもエラーになります。 [3]

netlify github連携#

netlifyにはgithubアカウントでログイン可能です。ログインしビルド対象のリポジトリ連携します。「New Site from git」から連携できます。

サイト確認#

https://jolly-brown-b98547.netlify.app/ のようなランダムなURLでサイトが公開されます。確認してみましょう

URLを独自ドメインに変更する#

ドメインを取得してURLを変更することが可能です。

ドメイン取得#

お試し用には無料で取得できる freenom を使います [5]

ドメインの設定#

公式サイトの「Configure an apex domain」という手順 [4] を参考に設定します。

ドメインプロバイダからは、netlifyが指定するDNSを設定します。netlifyDNS側ではNetlifyレコードという特殊なDNSレコードを設定します。

もう一つの別の方法として、ドメインプロバイダー側のDNSにAレコードとしてルートをNetlifyのLBのIPを直接指定し、CNAMEレコードをwwwからapexサブドメインへ設定する方法もあります。

独自ドメインで確認#

設定したURLにアクセスして確認します。成功するとhttpsでアクセスできます。失敗するとnetlifyの管理画面でエラー状況が表示されます。