🧃

Sphinxのドキュメントをgulpで自動生成して、ブラウザを自動リロードする

2022/09/22に公開

Gulp

Sphinx

tech

昔作ったけどすっかり忘れてたので記事にしました。

この記事の内容である最新版はリポジトリを作り直しました

「Sphinxで作成しているドキュメントを更新したら、ビルドとブラウザの自動更新まで行う」というのをやっていきます。

淡々と書いていきます！

環境構築

以下のDockerfileを作成します

Dockerfile

FROM node
# python,sphinxなどのインストール
RUN apt-get update \
	&& apt-get install python3 \
	&& apt-get install python3-pip -y \
	&& pip3 install --upgrade pip \
	&& pip3 install -U sphinx
# 作業場所(ディレクトリ)の指定
WORKDIR /usr/src/app
# gulpなどをインストール
RUN npm i -g gulp \
	&& npm i browser-sync \
	&& npm link gulp

docker-compose.yamlを作成します

docker-compose.yaml

version: '3'
services:
  gulp:
    container_name: sphinxgulp
    build:
      context: ./
      dockerfile: ./Dockerfile
    ports: 
    - 3000:3000
    volumes:
      - ./app/:/usr/src/app/work
    tty: true

appフォルダを作成します

今のところこんな感じです

以下のコマンドでコンテナを起動します

docker-compose up -d

最初はビルドで時間がかかるので少し待ちます

実行中のコンテナは以下のコマンドで確認できます

docker container ps

CONTAINER ID   IMAGE              COMMAND                  CREATED         STATUS         PORTS                                                  NAMES
a013e1e89b6b   sphinx_gulp        "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes   0.0.0.0:3000->3000/tcp, :::3000->3000/tcp              sphinxgulp

コンテナが実行されたら以下のコマンドでコンテナに入ります

docker container exec -it sphinxgulp bash

そしたらworkフォルダに移動します
→これはappフォルダと紐づいています。

cd work

ここで以下のコマンドでsphinxプロジェクトを作成します

sphinx-quickstart

色々聞かれますが適当に答えます

プロジェクトが作成されると、色々とファイルが作られています

root@a013e1e89b6b:/usr/src/app/work# ls
Makefile  _build  _static  _templates  conf.py  index.rst  make.bat

appフォルダでも確認することができます

そのままHTMLの作成をやってみます

make html

root@a013e1e89b6b:/usr/src/app/work# make html
Running Sphinx v5.1.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

ビルドが成功したら_build/html/index.htmlを開いてみます

以下のようなWelcomeページが作成されています

簡単に新規ページを作っておきます

appフォルダにpageフォルダを作成して、そこにpage.rstを作成します

page.rst

Page
==================================

これは追加したページです

これをindexからリンクさせます。
index.rstを修正します

index.rst

.. misaka documentation master file, created by
   sphinx-quickstart on Wed Sep 21 08:47:05 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to misaka's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./page/page


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

現時点での構成

これでまたmake htmlを行って、再度ビルドされたファイルを確認してみます

Pageへのリンクが追加されていてアクセスすると、新規作成したページが表示されます。

gulp

guplを使ってmake htmlコマンドとブラウザのリロードを自動化します。

ブラウザのリロードはbrowser-syncが行いますのでこちらも一緒にインストールしておきました。

appフォルダにgulpfile.jsを作成します。

gulpfile.js

const {watch,series,parallel} = require("gulp");
const browserSync = require("browser-sync").create();
const exec = require('child_process').exec;

// browserSyncを最初に初期化しておきます。
function initBrowserSync(cb) {
    browserSync.init({
        open: false,
        server:{
            baseDir:["_build/html"],
            index: 'index.html'
        }
    })
    cb()
}

// リロード処理
function reload(cb) {
    browserSync.reload();
    cb()
}

// 監視処理
// 終了させない
function watchfile() {
    watch(['page/**/*.rst', '*.rst'], { usePolling : true }, series(makehtml,reload))
}

// make htmlの実行
function makehtml(cb) {
    exec("make html", (err,stdout,stderr) => {
        console.log(stdout)
    })
    cb()
}

exports.default = series(makehtml, parallel(initBrowserSync, watchfile, reload));

ここでの鬼門はwatchです。

この場合は同フォルダにある.rstファイルを修正するか、pageフォルダの.rstファイルを修正した時に、makehtmlとreloadを行います。
- rstファイルはsourceフォルダに作成するなどしたほうがいいです。
cbは名前はなんでもいいのですが終了を知らせるコールバック関数です
- watchにはつけず実行せずです

以下のコマンドでgulpを実行します

gulp

すると色々と情報が出てきます

ttp://localhost:3000/にアクセスすると以下のように表示されています

page.rstかindex.rstのファイルを修正すると自動的にmake htmlコマンドが実行されて、ブラウザがリロードされます。

index.rstを修正するとログが流れる

ブラウザも自動でリロードされる

sphinxでのドキュメント作成作業が捗ります。

環境構築

gulp

Discussion