READMEが終わらない、、
コードを一通り作り終わり、さぁ公開するか！とするときに、READMEを書かなきゃいかんかったことを思い出し。
書き始めるのですが、、、書いても書いても終わらない、、、
そもそも、自分が人のライブラリ使うときは使ってみてる人のブログを見て、専用のdocumentページをみて、それでもどうにもならんかったらソースを見て、、と、READMEにそこまで期待するわけじゃないんですよね。。
きちんとしたdocumentationの方法と、公開の仕方をちゃんと調べますか。。
ドキュメントを生成しよう
pydoc
これまでみて見ぬふりを決め込んでたましたが、そうもいかんですね。
手元のubuntu dockerで実行、、、できない。
pipで入れるもの、、でも無いんですね。
私の環境ではpythonはOSの標準のものを使うようにしてますし、それに合わせてaptで導入。
$ apt install python-dev-is-python3
まずは、試してみる。
$ cd ./src
$ pydoc <My Pkg>
$ pydoc <My Pkg>.<My Module>
ドキュメント化したいファイルを指定するのではなく、モジュールを指定する方法となります。
pypiに上げるつもりで整理していると、./src/というようなディレクトリ配置にしてるでしょうから、srcの直下で上記のコマンドを打つ感じです。
雰囲気として、自分がローカルで引用するときに使うような用途なんですかね。
htmlとして出力もできるし、ウェブサーバとして起動することもできるとのことだけど、、
Github Pagesか、何かしらのウェブサービスに乗っける方法が今回のゴールイメージなので、これじゃない。
sphinx
まさにまとめて下さってる方が。
https://qiita.com/kinpira/items/505bccacb2fba89c0ff0
ただ、今回はすでに作成済みのパッケージを使うので、htmlファイル生成は以下の方法を参照させていただきます。
http://capm-network.com/?tag=Python_%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E7%94%9F%E6%88%90
$ pip3 install sphinx
$ sphinx-apidoc -F -o docs/ src/
$ cd ./docs
$ make html
ちなみに私の環境だとmakeも入れてないので、まずは apt install make からなんですが。。
実行してみると、htmlファイルとそれに使われるディレクト群はいいとして、、結構ワラワラ生成されるな。。
これイランものはgitに乗っけないような配慮をしたところだな。。
sphinxの生成物
上記で生成したディレクトリを見ると、以下のような構造になっている。
$ tree ./
./
|-- Makefile
|-- _build
| |-- doctrees
| | |-- <My PKG>.doctree
| | |-- <My PKG>.searchpath.doctree
| | |-- environment.pickle
| | `-- index.doctree
| `-- html
| |-- _modules
| | |-- <My PKG>
| | | |-- <My Module>.html
| | `-- index.html
| |-- _sources
| | |-- <My PKG>.rst.txt
| | |-- <My PKG>.searchpath.rst.txt
| | `-- index.rst.txt
| |-- _static
| | |-- alabaster.css
| | |-- basic.css
| | |-- custom.css
| | |-- doctools.js
| | |-- documentation_options.js
| | |-- file.png
| | |-- jquery-3.5.1.js
| | |-- jquery.js
| | |-- language_data.js
| | |-- minus.png
| | |-- plus.png
| | |-- pygments.css
| | |-- searchtools.js
| | |-- underscore-1.3.1.js
| | `-- underscore.js
| |-- <My PKG>.html
| |-- <My PKG>.searchpath.html
| |-- <My PKG>.html
| |-- index.html
| |-- objects.inv
| |-- py-modindex.html
| |-- search.html
| `-- searchindex.js
|-- _static
|-- _templates
|-- conf.py
|-- <My PKG>.rst
|-- <My PKG>.searchpath.rst
|-- index.rst
htmlディレクトリ配下だけあれば、Web公開には事足りそう。
で、よくお世話になってるパッケージを見ると、、docs配下に_build以外をおいている、、。
必要に応じて手元で生成できるようにはしておくけど、生成物は.gitignoreで排除してますね。
以下のGithub Pagesの公開の章で改めて考えます。
備考 pypi向けのアップ
sphinxで生成したファイルをpypiにアップする。
https://pythonhosted.org/an_example_pypi_project/buildanduploadsphinx.html
https://pypi.org/project/Sphinx-PyPI-upload/
でも大体のパッケージってpypiにはほとんど情報書かず、gitや自組織のdocページへのリンクを貼ってるんですよね。。
これは見送りで。
公開しよう
Github Pages
「指定のブランチの指定のディレクトリのコンテンツを、webpageとして公開する」。
。。。ちと考えないといけないですね。。
初心者の私から見ると、以下のどちらかの使い方を選ぶ感じでしょうか。
- ドキュメント配置専用の空ブランチ（ディフォだと"gh-pages")を新たに作って、そこにコンテンツを置く
- mainブランチの指定のディレクトリ（/docとか？）にコンテンツをおく
実際の用途を考え得ると、ソースの変更・テストと、ドキュメント化は、２ステップに別れる作業なんですよね。
なので、想定するワークフローは下のどちらかでしょうか。
A.「ソースを更新してテストする」「gitに上げる」「（Github Actionsとかで自動的に）doc化する」「docをgitに上げる」
B.「ソースを更新してテストする」「doc化する」「ソースとdocを一緒にgitに上げる」
Aでやりたいなら1、Bでやりたいなら2、てとこでしょうかね。
Aを2で実施できる方法もsphinxのユーザ会で紹介されてましたけど、gitに上げたものが自動で更新されるのはgit初級者からするとややっこしい。。チーム開発していれば他者がpushするのも当たり前なわけで、違和感ないのだろうけど、私はまだその領域にはたどり着けてないですね。。
https://sphinx-users.jp/cookbook/githubaction/index.html
gitでよく使わせていただいているパッケージの事例を参考にさせていただこうかなとgitを見ると、、うん、そもそもGithub Pagesつかっとらんですね。。
上のgitのdocsの掲載事例をみるに、gitでコード持ってった人がsphinxでdocを生成できるように、sphinx用の設定ファイルはアップしておくけど、sphixで生成したWebコンテンツ自体は別の方法で管理する、ということでしょうか。
上記のパターンに当てはめると、Aと1のペアに相当する方法ってことでしょうか。
一回その組み合わせで方法確立するか。
Doc専用ブランチの作成と、公開（初回編）
以下の手順に則って、レポジトリに対してgp-pagesの新規追加をする。
$ cd <PKG Directory>
# Sphinxでhtmlファイルを生成する
$ sphinx-apidoc -F -o docs/ src/
$ cd ./docs
# コンフィグファイル(conf.py)にて、以下を修正。
# 1. import sysと、sys.path.insert(..)のコメントアウトを外す。
# これをしないと、モジュールが見つからないというエラがー出ててしまう。
# 2. copyright, authorを適切に記入
#
# その後、改めてmake
$ make html
# first commitに戻す。（もっときれいな方法あるとは思うけど、、）
# 上記で生成したファイルは、git addしてないので、docs/_build/html配下はまるまる残ってる、、、はず、、
# addしてても、標準の.gitignoreに_buildが入っているはずなので、やっぱ残ってるはず、、、
$ git log | grep "^commit" | tail -n1 | cunt -d " " -f 2 | xargs -n1 git reset --hard
# 不要なファイルを消しとく
$ rm <不要ファイル群> #README.rstやLICENSE, .gitignoreなど、、かな、、、
# htmlファイルをルートに持っていく
# Github Pagesで公開対象のディレクトリを_build/htmlに限定しておけばいい気もするけど、、現状pros/consが思いつかないので、一応絞っとく。
$ mv ./docs/_build/html/* ./
$ rm -rf ./docs
# Webページ公開用のブランチを作る
$ git checkout -b gp-pages
# Gitにアップ
$ git add .
$ git commit -m "First Commit for gh-pages"
$ git push -u origin gh-pages
# Github Pages設定を有効化する
# https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
# Branchでph-pagesを指定。ディレクトリ指定はしない（gitのルートは以下のコンテンツをそのまま読み込む）。
# mainブランチに戻る
git checkout main
Docの更新（２回目以降）
# まず、変更分をコミットして、gitに上げておく。
$ cd docs
$ make html
$ git checkout gh-pages
$ mv ./docs/_build/html/* ./
$ rm -rf ./docs
$ git commit -m "Commit MSG"
$ git push -u origin ph-pages
処理の自動化
Github Actionsで、mainブランチがpushを受けたら、上記のDocの更新を実行して、gh-pagesにプッシュする、って方法。
pushの認証は、いくらGuthubのSecretsを使うと言っても流石にパスワードを登録するのも気持ち悪いし、レポジトリ専用のsshキーペアを作り、sshでプッシュする方法を使うことにする。
以下の方法を使わせていただく。
https://sphinx-users.jp/cookbook/githubaction/index.html
ssh鍵の作成と、gitへの登録
手元でssh鍵を作り、公開鍵をレポジトリのDeployment keyに登録しておく。
秘密鍵はSecretに登録し、Actionで都度呼び出してssh接続に使う。
鍵の登録方法は、上記のsphinxのサイトを参照。
今回は、Secretsに"UPLOADKEY"という名称で登録する。
Gtihub Actions用のコンフィグ調整
Github Actionsでは、処理は/home/runner/work//で実行されるっぽい。
この際、conf.pyでソースディレクトリのパスを通すところをちょっと工夫してやらないといけない。
$ vi ./docs/conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
make htmlはおそらくdocsのは以下で実施するので、そこからの相対パスでソースの配置場所を動的に設定する。
Github Actions
mainレポジトリの.git/workflowに、以下を配置する
$ cat .github/workflow/main.yaml
name: Generate Document
on:
push:
branches: [ main ]
workflow_dispatch:
jobs:
documemtation:
runs-on: ubuntu-latest
steps:
- uses: actions/setup-python@v2
with:
python-version: '3.x'
- uses: actions/checkout@v2
with:
fetch-depth: 0
# fetch-depthの設定を入れないと、最新のレポジトリしか持ってこないので、gh-pagesがなくてチェックアウトできなくなる。
- name: Install sphinx
run: pip3 install sphinx
- name: Install requirements
run: pip3 install -r requirements.txt
- name: Make HTML
run: make html
working-directory: ./docs
- name: Change Branch
run: git checkout gh-pages
- name: Clean directories
run: find -mindepth 1 -maxdepth 1 -type d -not -name "docs" -and -not -name ".git" | xargs -n1 rm -rf
- name: Arrange html files
run: |
mv -f ./docs/_build/html/* ./
rm -rf ./docs
- name: Setup SSH
run: |
mkdir ~/.ssh
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
echo "${{ secrets.UPLOADKEY }}" > ~/.ssh/id_rsa
chmod 400 ~/.ssh/id_rsa
- name: Commit and Push
env:
GITHUB_USER: "<User Name>"
GITHUB_EMAIL: "<Mail Address>"
run: |
git config --local user.name "${GITHUB_USER}"
git config --local user.email "${GITHUB_EMAIL}"
git add .
git commit -m "Auto documentation"
git push origin gh-pages
とりあえずちゃんと動きますね。
でも、思ったほどドキュメントサイト見やすくないな。。。デザインが悪いのだろうか。
もうひとひねり必要そうですね。
まぁそれはおいおい。