Sphinx出力HTMLのサイズと動作のテーマ毎比較

Google Ad

本記事の主旨

Sphinxで出力したHTMLのサイズとサンプルページをテーマ毎に比較する。

比較の目的

　比較の目的を以下に記す。

  • テーマごとに出力したHTMLのサイズを確認する。
    • テンプレートでサイズを確認する。
    • 公認のサンプルソースでサイズを確認する。
  • テーマごとに出力したHTMLのサンプルページを確認する。
    • テンプレートで挙動を確認する。
    • 公認のサンプルソースで挙動を確認する。

使用したライブラリ等のバージョン

以下のバージョンを使用した。

  • Python 3.10.9
  • pip 23.3.1
  • Sphinx 7.2.6

出力したHTMLサイズの比較方法

テンプレートでのサイズ確認には、Sphinxのプロジェクト作成時に自動生成されるものを使用する。

公認のサンプルソースは以下のものを使用する。

それぞれのテーマでビルドしてできた、HTMLのサイズを比較する。

このとき、以下の公式のページに書かれている組み込みテーマを使用する。

出力したHTMLサイズ比較

手順

以下の手順で比較した。

Sphinxのインストール

1. 以下のコマンドでインストールした。

PS E:\実験\Sphinx> pip install sphinx

2. 以下のコマンドでバージョン確認した。

PS E:\実験\Sphinx> sphinx-quickstart --version
sphinx-quickstart 7.2.6

Sphinxでプロジェクト作成

以下のようにプロジェクトを作成した。

1. sphinx-quickstartコマンドでコマンドライン引数の第一引数をテーマ名とした。これでテーマ名をフォルダ名とするフォルダの中にプロジェクトができる。

例：sphinx-quickstart alabaster

2. プロジェクト作成時は対話形式で設定を入力する。それぞれ以下のように入力した。

  • > Separate source and build directories (y/n) [n]: y
  • > Project name: test
  • > Author name(s): kojichu.com
  • > Project release []: 0.01
  • > Project language [en]: ja

alabasterテーマのプロジェクトを作成したときのログは以下である。

PS E:\実験\Sphinx> sphinx-quickstart alabaster
Welcome to the Sphinx 7.2.6 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: alabaster

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: test
> Author name(s): kojichu.com
> Project release []: 0.01

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ja

Creating file E:\実験\Sphinx\alabaster\source\conf.py.
Creating file E:\実験\Sphinx\alabaster\source\index.rst.
Creating file E:\実験\Sphinx\alabaster\Makefile.
Creating file E:\実験\Sphinx\alabaster\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file E:\実験\Sphinx\alabaster\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

公式サイトに書かれた組み込みテーマらしきテーマごとにプロジェクトフォルダを作成した。以下のようなフォルダがある。

PS E:\実験\Sphinx> Get-ChildItem


    ディレクトリ: E:\実験\Sphinx


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2023/11/21     21:15                agogo
d-----        2023/11/21     21:06                alabaster
d-----        2023/11/21     21:18                basic
d-----        2023/11/21     21:17                bizstyle
d-----        2023/11/21     21:13                classic
d-----        2023/11/21     21:19                epub
d-----        2023/11/21     21:16                haiku
d-----        2023/11/21     21:16                nature
d-----        2023/11/21     21:17                pyramid
d-----        2023/11/21     21:15                scrolls
d-----        2023/11/21     21:14                sphinxdoc
d-----        2023/11/21     21:19                sphinx_rtd_theme
d-----        2023/11/21     21:15                traditional

これらのフォルダの構造は以下のようになっている。以下はalabasterの例である。

PS E:\実験\Sphinx\alabaster> tree /f

E:.
│  make.bat
│  Makefile
│
├─build
└─source
    │  conf.py
    │  index.rst
    │
    ├─_static
    └─_templates

Sphinxのビルド設定

各プロジェクトフォルダのsourceフォルダ内のconf.pyにあるhtml_themeの値を変更する。

Sphinxのビルド（テンプレート）

各プロジェクトフォルダ内で.\make htmlコマンドを打つ。

alabasterテーマでHTMLをビルドしたときのログは以下である。

PS E:\実験\Sphinx\alabaster> .\make html
Running Sphinx v7.2.6
loading translations [ja]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
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
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in Japanese (code: ja)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

epubはいかにも電子書籍用の名前であるが、HTMLのビルドには成功した。

Read The Docsのテーマはビルドできなかったため、組み込みテーマではないことが分かった。

以下がRead The Docsのテーマをビルドしようとしたときのログである。

PS E:\実験\Sphinx\sphinx_rtd_theme> .\make html
Running Sphinx v7.2.6
loading translations [ja]... done
making output directory... done

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

Sphinxのビルド（公認のサンプルソース）

以下のソースのsample-docsの中身をプロジェクトフォルダ内のsourceフォルダ傘下に置く。

このときのフォルダの構造は以下のようになっている。以下はalabasterの例である。

sample-docsの中身由来のものに★を付けた。

PS E:\実験\Sphinx\sample\alabaster> tree /f

E:.
│  make.bat
│  Makefile
│
├─build
└─source
    │  conf.py
    │  index.rst　★
    │  long-page.rst　★
    │  placeholder-four.rst　★
    │  placeholder-one.rst　★
    │  placeholder-three.rst　★
    │  placeholder-two.rst　★
    │  really-long-title.rst　★
    │
    ├─kitchen-sink　★
    │      admonitions.rst　★
    │      api.rst　★
    │      blocks.rst　★
    │      generic.rst　★
    │      images.rst　★
    │      index.rst　★
    │      lists.rst　★
    │      really-long.rst　★
    │      structure.rst　★
    │      tables.rst　★
    │      typography.rst　★
    │
    ├─_static
    └─_templates

各プロジェクトフォルダ内で.\make htmlコマンドを打つ。

alabasterテーマでHTMLをビルドしたときのログは以下である。

ここでエラーが出ているように見えるが、最終的にはワーニング扱いであるためビルドできたとする。

PS E:\実験\Sphinx\sample\alabaster> .\make html
Running Sphinx v7.2.6
loading translations [ja]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 18 source files that are out of date
updating environment: [new config] 18 added, 0 changed, 0 removed
reading sources... [100%] really-long-title
E:\実験\Sphinx\sample\alabaster\source\index.rst:18: ERROR: Unknown directive type "theme-install".

.. theme-install::
E:\実験\Sphinx\sample\alabaster\source\index.rst:22: ERROR: Unknown directive type "theme-configuration".

.. theme-configuration::
E:\実験\Sphinx\sample\alabaster\source\index.rst:3: ERROR: Undefined substitution referenced: "theme_display".
E:\実験\Sphinx\sample\alabaster\source\index.rst:5: ERROR: Undefined substitution referenced: "theme_display".
E:\実験\Sphinx\sample\alabaster\source\index.rst:30: ERROR: Undefined substitution referenced: "theme_documentation_message".
E:\実験\Sphinx\sample\alabaster\source\kitchen-sink/admonitions.rst:93: ERROR: Unknown directive type "todo".

.. todo::

   This needs the ``sphinx.ext.todo`` extension.
E:\実験\Sphinx\sample\alabaster\source\kitchen-sink/api.rst:28: ERROR: Unknown directive type "automodule".

.. automodule:: urllib.parse
    :members:
E:\実験\Sphinx\sample\alabaster\source\kitchen-sink/blocks.rst:138: WARNING: Include file 'E:\\実験\\Sphinx\\sample\\src\\furo\\__init__.py' not found or reading it failed
E:\実験\Sphinx\sample\alabaster\source\kitchen-sink/lists.rst:202: WARNING: Include file 'E:\\実験\\Sphinx\\sample\\src\\furo\\__init__.py' not found or reading it failed
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] really-long-title
E:\実験\Sphinx\sample\alabaster\source\kitchen-sink\api.rst:10: WARNING: 'any' reference target not found: sphinx.ext.autodoc
generating indices... genindex done
writing additional pages... search done
dumping search index in Japanese (code: ja)... done
dumping object inventory... done
build succeeded, 10 warnings.

The HTML pages are in build\html.

サイズ比較

以下では、HTMLサイズを比較する。

テンプレート

テンプレートのreStructuredTextのサイズは448 バイト (448 バイト)である。

ビルドしたHTMLのサイズは以下の通りだった。

  • agogo：76.3 KB (78,153 バイト)
  • alabaster：76.9 KB (78,790 バイト)
  • basic：62.1 KB (63,685 バイト)
  • bizstyle：121 KB (123,968 バイト)
  • classic：73.5 KB (75,286 バイト)
  • epub：69.1 KB (70,781 バイト)
  • haiku：71.6 KB (73,395 バイト)
  • nature：71.5 KB (73,235 バイト)
  • pyramid：86.4 KB (88,556 バイト)
  • scrolls：164 KB (168,169 バイト)
  • sphinxdoc：73.1 KB (74,955 バイト)
  • traditional：74.7 KB (76,514 バイト)

公認のサンプルコード

公認のサンプルコードのreStructuredTextのサイズは75.4 KB (77,305 バイト)である。

ビルドしたHTMLのサイズは以下の通りだった。

  • agogo：407 KB (417,492 バイト)
  • alabaster：401 KB (410,965 バイト)
  • basic：386 KB (395,285 バイト)
  • bizstyle：448 KB (459,630 バイト)
  • classic：397 KB (407,124 バイト)
  • epub：321 KB (329,234 バイト)
  • haiku：346 KB (354,424 バイト)
  • nature：395 KB (404,852 バイト)
  • pyramid：417 KB (427,958 バイト)
  • scrolls：447 KB (458,067 バイト)
  • sphinxdoc：397 KB (406,623 バイト)
  • traditional：398 KB (408,216 バイト)

まとめ

reStructuredTextのサイズが増加すると、テーマごとのHTMLビルド後のサイズのばらつきが縮小することがわかった。

出力したHTMLサンプル比較

テンプレート

どれもサクサク動き、違いは特になかった。

公認のサンプルソース

以下のサイトで挙動を確認できる。

Sphinxで作成したサイトと書籍一覧

公式サイトに、Sphinxで作成したサイトと書籍の一覧がある。

広告

Sphinxのインストールやビルドについて書かれた本。初心者向けで基本的なことのみ書かれている。

reStructuredTextの使い方が詳しく書かれているため、reStructuredTextを使用するには一番参考になる本。

広告

フリーソフト,文章調査,Python,WEB技術,HTML,Sphinx,Read The Docs

Posted by kojichu