ドキュメントの継続的改善―Sphinxを使いながら

ドキュメントの継続的改善
Sphinxを使いながら
株式会社アプトポッドテクニカルコンテンツディレクター
篠崎宗一郎
© aptpod Inc. All Rights Reserved. 1
2 0 2 3 / 0 7 / 1 3

自己紹介
2
© aptpod Inc. All Rights Reserved.
• 所属
• 株式会社アプトポッド https://www.aptpod.co.jp/
• 担当
• テクニカルコンテンツディレクター
• 参考テックブログ記事: 「ひとりドキュメント担当」 *の仕事
https://tech.aptpod.co.jp/entry/2021/12/20/070000
• 職歴
• 2001-2008 マニュアル制作会社多言語制作コーディネーター
• 2010-2020 メーカー子会社マニュアル制作部門ライター、ディレクター
• 2020- 現職
* 「ひとり情シス」になぞらえたものです。

この発表の内容とゴール
© aptpod, Inc. All Rights Reserved. 3
• 内容
• Sphinxを使ったドキュメント制作事例の紹介
• ゴール
• 「Sphinxってこういうものなんだ」と思っていただく
• 「多機能で柔軟でいろいろできそうだな」と思っていただく
• 「自分の道具箱にも入れておこうかな」と思っていただく

目次
• 前置き: アプトポッドについて
• 1. Sphinxってどんなもの？
• 2. Sphinxを採用した理由
• 3. Sphinxの柔軟さを活用しながらカスタマイズ・改善
• まとめ

アプトポッドについて

アプトポッドについて
• 「高頻度データ」を「低遅延で」伝送するIoTの仕組みをつくっています
• データ取得デバイスから、サーバーソフトウェア、アプリケーションまで
• デバイスとサーバーの間をつなぐ独自プロトコル（iSCP）
• 可視化ダッシュボードも

アプトポッドの製品が実現する産業IoTシナリオ

例: 自動車からデータを取得
https://www.youtube.com/watch?v=vybSwUoDMcY&t=5s

• ハードウェアマニュアル
作っているドキュメントその1
PDF
↑ これらはすべてSphinxで制作

© aptpod, Inc. All Rights Reserved. 1 0
• ウェブアプリケーションの操作マニュアル
PDF
HTML

• 開発者向けガイド
PDF
HTML

1. Sphinxってどんなもの？

Sphinxとは
• documentation generator*1
• reStructuredText記法で書いたもの*2をPDFやHTML形式で出力す
るツール
*1 https://www.sphinx-doc.org/ja/master/usage/quickstart.html
*2 MySTをインストールするとMarkdownの利用も可能
画像
（png他）
PDF
HTML
LaTeX
設定
conf.py
テキスト
（reStructuredText）
Sphinxプロジェクト（ディレクトリ）

reStructuredText（Sphinx用）
© aptpod Inc. All Rights Reserved. 1 4
章レベル
========
これは本文です。 ``inline code`` です。
節レベル（章の下のレベル）
--------------------------
これは本文です。
項レベル（節の下のレベル）
~~~~~~~~~~~~~~~~~~~~~~~~~~
これは本文です。
見出しと本文
右側はHTMLに変換した場合の一例です。
設定によって見かけは異なります。

* 番号なしリスト
1. 番号付きリスト
リスト

.. figure:: images/sample.png
図のサンプル
図

.. code-block:: json
{
"key1": 1,
"key2": 2
}
コードブロック

.. list-table::
:widths: 1 2 2
:header-rows: 1
* - 列ラベル
- 列ラベル
- 列ラベル
* - セル1-1
- セル1-2
- セル1-3
* - セル2-1
- セル2-2
- セル2-3
表の表現方法は他にもありますが、この
「list-table」を一番よく使っています。
表（list-tableの場合）

.. note::
この部分は「注釈」になります。
.. important::
この部分は「重要」になります。
.. warning::
この部分は「警告」になります。
注釈、警告等（admonition）

インストールの方法については、
:ref:`installation` を参照してください。
.. _installation:
インストール
----------------
インストールはこのように行います。
相互参照（リンク）

2. Sphinxを採用した理由

Sphinxを採用した理由 1
• きれいな日本語PDFが作れる（LaTeX経由）

• 翻訳ワークフローに対応
画像
（png他）
PDF
HTML
LaTeX
設定
conf.py
日本語テキスト
日英対訳POファイル
（Gettext PO）
日本語→英語の場合

• 機能拡張や情報が豊富
• 機能拡張
• テーマ（HTML出力のテンプレート）
• 使い方についての情報

使い方についての情報
• 公式ドキュメント
• https://www.sphinx-doc.org/ja/
• 書籍『Sphinxをはじめよう』
• https://www.oreilly.co.jp/books/9784873119830/
• ネット上にも情報は豊富
• Stack Overflowで [python-sphinx]タグが付いた質問は3600以上

Sphinxで作成した結果
PDF

Sphinxで作成した結果
HTML

3. Sphinxの柔軟さを活用しながら
カスタマイズ・改善

改善してきたことのうちいくつかをご紹介
• A. PDFスタイルのカスタマイズ
• B. HTML化
• C. 検索エンジンMeilisearchの導入（HTML用）
Sphinxには、これ以外にも便利な機能はたくさんありますし、同様のことを実現するた
めのもっと良い方法もあるかもしれません。
ここで紹介する方法がすべてではないということをご了承ください。

A. PDF出力のカスタマイズ
• 表紙
• ヘッダー、フッター
• 目次のスタイル
• 章・節・項タイトルのスタイル
• 警告・注意などの囲みのスタイル

カスタマイズの入り口設定ファイルconf.py
画像
（png他）
PDF
LaTeX
設定
conf.py
テキスト
HTML

設定ファイルconf.py
# -- Project information -----------
project = 'テストドキュメント'
copyright = '2023, my name'
author = 'my name'
release = 'v1.0'
# -- General configuration ----------
extensions = []
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
language = 'ja'
# -- Options for HTML output ---------
html_theme = 'alabaster'
html_static_path = ['_static']
...以下略

PDF出力のカスタマイズ
• Sphinxでパラメーターが用意されているものはそれを変更
• ただし、設定可能なパラメーターは少ない
例：
latex_show_pagerefs = True
設定ファイルconf.pyに以下を追加

PDF出力のカスタマイズ
• latex_elementsのpreambleにLaTeXのコードを書く
latex_elements = {
'preamble': '<ここに書いたものは、LaTeXプリアンブルとして出力される>'
}
（または、外部ファイルに書いて読み込ませるように設定）

例1: 章番号のカスタマイズ

• latex_elementsのpreambleにLaTeXのコードを書く
latex_elements = {
'preamble': r'''
renewcommand{prechaptername}{}
renewcommand{postchaptername}{}
'''
}

例2: PDF表紙のカスタマイズ

表紙の中身
newcommand{sphinxmaketitle}{%
letsphinxrestorepageanchorsettingrelax
ifHy@pageanchordefsphinxrestorepageanchorsetting{Hy@pageanchortrue}fi
hypersetup{pageanchor=false}% avoid duplicate destination warnings
begin{titlepage}%
letfootnotesizesmall
letfootnoterulerelax
noindentrule{textwidth}{1pt}par
begingroup % for PDF information dictionary
defendgraf{ }defand{& }%
pdfstringdefDisableCommands{def{, }}% overwrite hyperref setup
hypersetup{pdfauthor={@author}, pdftitle={@title}}%
...続く
Sphinxに付属のLaTeXコマンド「sphinxmaketitle」
（デフォルトだとこのコマンドが使われるということがSphinxのドキュメントに書いてあ
ります）

latex_elements = {
'preamble': r'''
makeatletter
newcommand{mysphinxmaketitle}{%
letsphinxrestorepageanchorsettingrelax
ifHy@pageanchordefsphinxrestorepageanchorsetting{Hy@pageanchortrue}fi
hypersetup{pageanchor=false}% avoid duplicate destination warnings
begin{titlepage}%
letfootnotesizesmall
letfootnoterulerelax
...省略...
}
makeatother
''',
'maketitle': r'mysphinxmaketitle'
}
表紙作成時には上記コマンドを使うようSphinxに指示
新しい表紙用コマンドを定義してLaTeXプリアンブルに入れる

望みのPDFスタイルに
Word（過去の版） Sphinx

LaTeXの世界
• おすすめ書籍

B. HTML化
• もともとSphinxは、HTML、PDF、ePubなどさまざまな出力ができる
• 基本的には、HTML出力するコマンド(make html)を実行するだけで
よい

使用テーマ
• Read the Docs Sphinx Theme

使用テーマ
• PyData Sphinx Theme

複数プロジェクトを統合
• いくつかの冊子だったものを1つのサイトに統合
• そのうえで、複数のPDF分冊として出力するよう設定
Sphinx
Project A
統合したSphinx Project
Sphinx
Project B
Sphinx
Project C
アプリA説明書
PDF
アプリB説明書
PDF
アプリC説明書
PDF HTML
アプリA説明書
PDF
アプリB説明書
PDF
アプリC説明書
PDF

1つのプロジェクトで複数のPDFを出力する
latex_documents = [
# (PDF出力対象の各ドキュメントroot, LaTeXファイル名, ..以下略)
('app-a/index', 'app-a.tex', ...),
('app-b/index', 'app-b.tex', ...),
('app-c/index', 'app-c.tex', ...),
]

タブの表現
• sphinx-tabsという拡張
• インストール
• 設定ファイルconf.pyに extensions = ['sphinx_tabs.tabs'] を指定
.. tabs::
.. tab:: Go
プロジェクトルートにて以下の...
.. tab:: Python
.....
.. tab:: Rust
.....

コードブロックのコピーボタン
• sphinx-copybuttonという拡張
• インストール
• 設定ファイルconf.pyに extensions = ['sphinx_copybutton'] を指定

Googleアナリティクス導入
Read the Docs Sphinx Themeや、PyData Sphinx Themeでは、設
定ファイルconf.pyにGoogleアナリティクスIDを設定するだけ
html_theme_options = {
'analytics_id': 'G-XXXXXXXXXX'
}
設定ファイルconf.py （ Read the Docs Sphinx Themeの場合）

C. 検索エンジンMeilisearchの導入（HTML用）
• Meilisearchという全文検索エンジンを導入
参考: Vさんが公開されている記事
https://voluntas.medium.com/オンラインドキュメントと日本語全文検索-30cc38d7b1c3

Meilisearchを使うための準備1
• 専用ツールでドキュメントをスクレイピングして、できたインデックス
をMeilisearchサーバーに送る
Meilisearchサーバー
docs-scraper
（Meilisearchの
専用スクレイピングツール）
インデックスを
アップロード
ページを取得

Meilisearchを使うための準備2
• SphinxのHTMLテーマをカスタマイズする
• 検索ボックスを、Meilisearchが提供する docs-searchbar.js
(https://github.com/meilisearch/docs-searchbar.js) に差し替える
• 前ページの手順で作成したインデックスを使用するように指定する
Meilisearchサーバー
Sphinxテーマのなかで、
検索ボックスの部分を
差し替え
検索クエリ
結果

柔軟であるということ
• カスタマイズが可能な個所がいくつもある
• 設定ファイルconf.pyでの設定
• 機能拡張の利用
• (HTML) テーマの一部を置き換え
• (HTML) CSS追加読み込み
• (PDF) LaTeXコードの追加（コマンド再定義など）
• などなど...

カスタマイズ情報の入り口
• 設定
https://www.sphinx-doc.org/ja/master/usage/configuration.html

今後の課題として考えていること
• ウェブサイトとして利用しやすい形に構造を整理
• HTMLページのスタイルの改善
• TMS（翻訳マネージメントシステム）の利用

まとめ

まとめ
• Sphinxはとても便利
• PDFを（も）作成したい場合は特に。
• Sphinxは多機能
• 期待に応えてくれる。
• Sphinxは柔軟
• 設定やカスタマイズが可能な部分がいろいろなところに用意されているので、
少しずつ制作物を改善していくのにも向いている。

ドキュメントの継続的改善―Sphinxを使いながら

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to ドキュメントの継続的改善―Sphinxを使いながら

Similar to ドキュメントの継続的改善―Sphinxを使いながら (20)

Recently uploaded

Recently uploaded (9)

ドキュメントの継続的改善―Sphinxを使いながら