Skip to content

Instantly share code, notes, and snippets.

@number09

number09/publish-sphinx-document-on-github-pages.md

Last active May 12, 2021 22:56
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save number09/d6a2753b8c3fcd74b15e0eab6763aa94 to your computer and use it in GitHub Desktop.
Save number09/d6a2753b8c3fcd74b15e0eab6763aa94 to your computer and use it in GitHub Desktop.
Download ZIP
GitHub PagesでSphinxドキュメントを公開する手順
Raw
publish-sphinx-document-on-github-pages.md

GitHub PagesでSphinxのビルドHTMLファイルを公開する

目的

  • 野良翻訳したSphinxドキュメントをGitHub Pagesを使って公開したい
    • masterブランチはfork元のままにしておきたい
      • masterブランチのdocフォルダを公開する機能は使えない想定
    • 翻訳作業はtrans-jaブランチで行う
    • 翻訳後ビルドしたHTML等をgh-pagesブランチに登録し公開する

手順作成方針

  • sphinx-ghp-testリポジトリでテスト
  • masterブランチにはビルド結果ファイル(HTML等)は登録しない
    • 実際はtrans-jaブランチとなる想定
  • gh-pagesブランチにはビルド結果ファイルのみ登録する

手順

  • GitHub上でリポジトリを作成

    • sphinx-ghp-test

  • ローカルにclone

    • git clone git@github.com:number09/sphinx-ghp-test.git
    • 現在のディレクトリにsphinx-ghp-testのディレクトリが作成される

  • sphinx-ghp-testディレクトリへ移動

    • cd sphinx-ghp-test
    • 現在のブランチ:master

  • プロジェクト用の仮想環境をpython3 -m venv (任意の名前）で作成する

    • venvという名前にする
    • python3 -m venv venv

  • 仮想環境に入った上で、pipコマンドでSphinxをインストールする

    • source venv/bin/activate
    • pip install sphinx

  • sphinx-quickstartコマンドでSphinxの初期ファイルを生成する

    • sphinxのバージョンは1.8.4を使用
      • 以下はデフォルトから変更した項目
        • 言語は"ja"を指定
        • ドキュメント名、作成者は任意
        • .nojekyllファイルを作成する
          • ビルドしたHTMLをGithub Pagesで正しく表示するために必要
        • make.batファイルは作成しない

  • 仮想環境のvenvディレクトリは管理しないので.gitignoreに記述

    • touch .gitignoreでファイルを生成
    • .gitignoreファイルにvenvを追記

  • 一旦.gitignoreファイルだけcommit & pushしておく

    • git add .gitignore
    • git commit -m"add .gitignore"
    • git push

  • 空っぽのgh-pagesブランチを作成 & チェックアウトする

    • git checkout --orphan gh-pages
      • 通常のブランチ作成は、現在のブランチを元に作成するが、
        --orphanを付けることで、過去の歴史の無いブランチが作成出来る
    • 上記コマンドで、現在のブランチがgh-pagesに変更になっている
    • ただしまだgit branchしてもブランチ一覧に表示されない状態

  • gh-pagesブランチに空のREADME.mdファイルだけコミットする。何でもいいので一度コミットが必要

    • 現在の状態を確認
      • git status 
        On branch gh-pages

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

	new file:   .gitignore
	new file:   Makefile
	new file:   conf.py
	new file:   index.rst
    • 4つのファイルがステージされているので、アンステージする（コミット待ち状態を取り消す）
      • git rm --cached $(git ls-files)
    • 再確認
      • git status 
        On branch gh-pages

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	.gitignore
	Makefile
	conf.py
	index.rst

nothing added to commit but untracked files present (use "git add" to track)
    • ファイル作成 & コミット
      • touch README.md
      • git add README.md
      • git commit -m"create gh-pages branch"
    • 確認
      • git branch 
        * gh-pages
  master
    • gh-pagesブランチをリモートリポジトリ(GitHub)へpush
      • git push -u origin HEAD

  • masterブランチでの作業に戻る

    • git checkout -f master
      • -fでローカルファイルに変更があっても、masterの内容で強制上書きする
    • この時点でのディレクトリの中身(ls) 
      Makefile   conf.py    index.rst  venv/

  • _build/htmlディレクトリはビルドしたHTML等が出力されるフォルダ
    このディレクトリにgh-pagesブランチの内容を展開する

    • git submodule add -b gh-pages git@github.com:number09/sphinx-ghp-test.git _build/html
      • 注意1 gh-pagesブランチがあり、ファイルを一度コミットしている必要がある
      • 注意2 指定したディレクトリ(この場合_build/html)が無い状態で上記コマンドを実行する
        • ディレクトリがあるとalready existsといわれてエラーになる
    • この時点で、build/htmlディレクトリにREADME.mdファイル(gh-pagesの内容)が作成されている

  • 状態を確認

    • git status 
      On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	new file:   .gitmodules
	new file:   _build/html
    • .gitmodulesファイルが作成されているのでコミットする
      _buildディレクトリがステージされているのでアンステージし、バージョン管理外にする
      • git reset _build/html
      • git commit -m"add .gitmodules"
      • git push
      • .gitignoreファイルに_buildを追記
      • git add .gitignore
      • git commit -m"update .gitignore"
      • git push

  • Sphinxドキュメントをビルドする

    • make html
    • _build/htmlディレクトリ(README.mdファイルがある位置)に出力される

  • masterブランチの状態確認

    • git status 
      On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
      • ビルドしたファイルが出力されたが、_buildディレクトリはバージョン管理外になっている為(?)
        変更なしとされる

  • _build/htmlディレクトリ内でgh-pagesブランチの状態確認

    • cd _build/html
    • git status 
      Your branch is up to date with 'origin/gh-pages'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	.buildinfo
	.nojekyll
	_sources/
	_static/
	genindex.html
	index.html
	objects.inv
	search.html
	searchindex.js
	venv/

nothing added to commit but untracked files present (use "git add" to track)

  • サイトで公開したいファイルをgh-pagesブランチにcommit & pushする

    • git add .buildinfo .nojekyll _sources _static genindex.html index.html objects.inv search.html searchindex.js
    • git commit -m"build html"
    • git push

  • GitHub Pagesでは、https://number09.github.io/sphinx-ghp-test/ で表示出来る

参考

http://sphinx-users.jp/cookbook/hosting/index.html#id6

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment