1. Sphinx のインストール方法

1.1. Sphinx とは

Sphinx は、reStructuredText記法で書かれた文章作成ツールで、テキストファイルをHTMLサイトword文章、 PDFやepubなどの様々な形式へ変換できる。

特に、数式、図などが混在する文章を作成するのに便利である。

Pythonの公式ドキュメントは Sphinx を使って書かれて、 また、Python以外の多くのプロジェクトでも Sphinx が利用されている。

Restructured text:

Sphinx での文章ファイルは単なるテキストファイルであるが、様々なルールの 下で記述されていると文章の修飾を行うことができる。この文章フォーマットを Restructured text と呼ばれる。

• 通常

  通常のプログラムでは、pdf、htmlは別々のソフトで作成し、そのための 文章を書かなくてはならない。

  

• sphinx の場合

  sphinx の場合は、一つのファイルから様々なフォーマットで 文章を作成することができる。

  

1.2. sphinx の文章作成環境の設定

1.2.1. 動作環境について

この文章は、xubuntu 22.04 における使用を想定しているが、versionが変わればうまく動作しないので 注意すること。最初にlatexをインストールしておかないといけない。ポイントはtexliveではなくtexlive-science をインストールすることである。

リスト 1.1 tex環境の設定例

$ sudo apt-get -y install texlive-science # 本体
$ sudo apt-get -y install texlive-lang-cjk # 日本語版 (UTF8 対応)
$ sudo apt-get -y install xdvik-ja # プレビューを見るのに必要
$ sudo apt-get -y install dvipsk-ja # DVI から PostScript への変換用
$ sudo apt-get -y install gv #  Ghostscript 、 ps 形式の図を取り込んだ文書の作成用
$ sudo apt-get -y install texlive-fonts-recommended texlive-fonts-extra # TeX 用フォント

sphinx のインストールは、

$ sudo apt-get install python3-sphinx

によってインストールできる。バージョンは1.85になるはずである。

python3ではencodingはデフォルトで utf-8 となったため、環境設定はシンプルになった。

1.2.2. よく使うユーティリティと必要なモジュールのインストール

必要なモジュール等のインストールを terminal を開いて以下のコマンドで インストールを行う。

• retextとrst2pdf

$ sudo apt-get install rst2pdf retext kate

retetxt :

Restructured text用のeditorである。

kate :

Restructured textにも対応しているeditorでこちらの方が使いやすい。

rst2pdf :

rstからpdfへの出力するソフト。今回は、このソフト経由でsphinxのpdf出力を生成しない。 あまりオススメでない。

• JavaScript用数式パッケージ jsmath

$ sudo apt-get install jsmath

jsmath:

この拡張機能は、数式をそのままHTMLファイルに埋め込みます。JavaScriptのパッケージ

• blockdiag系の拡張のインストール

$ sudo apt-get install python3-sphinxcontrib.actdiag
$ sudo apt-get install python3-sphinxcontrib.blockdiag
$ sudo apt-get install python3-sphinxcontrib.nwdiag
$ sudo apt-get install python3-sphinxcontrib.seqdiag
$ sudo apt-get install python3-sphinxcontrib.spelling

blockdiag:

ブロック図をテキストから生成するソフト。ただし、日本語を使う際にはひと工夫が要る。

• graphviz 組み込み拡張機能なのでインストールの必要なし

graphviz:

有向性グラフをテキストから生成するソフト。blockdiagと違い日本語が簡単に使えるので便利

• html用のthemeのインストール

$ sudo apt-get -y install python3-sphinx-rtd-theme

レスポンシブのwebページになるので大変見やすい。

• latex用のmhchemとsiunitx

化学系文章でよく出てくる化学式や単位混在の数値などは latexで設定するのは大変なので、mhchemとsiunitxの２つのlatexパッケージを組み込む。 これらのパッケージはtexlive-scienceをインストールすると含まれているので、後述の conf.py を変更するだけで良い。

mhchem:

化学式などを書くのに便利なtexの拡張機能

siunitx:

単位や数値などを書くのに便利なtexの拡張機能

chemfig:

化学構造式をテキストで書くのに便利なtexの拡張機能

1.2.3. jupyter-notebookとの連携

ますは必要なモジュールをインストールする。

$ sudo apt-get install -y pandoc

$ sudo apt-get -y install python3-nbsphinx

$ sudo apt-get -y install python3-recommonmark python3-commonmark

pandoc:

汎用の文章コンバータ

nbsphinx:

sphinxの文章に直接jupyter-notebookの *.ipynb を読み込むモジュール

commonmark:

sphinxをMarkdownに対応させる

1.3. conf.py の設定例

latexの出力を調整しようとすると source directory に存在する conf.py を変更しなくてはならない。

以下に、設定のポイントを示す。

1.3.1. code-blockのフォントサイズの調整

コードを文章に挿入する際はフォントを小さめにしておくとよい。 conf.py の先頭の方に以下を挿入する。フォントサイズは20行目のところを変える。 下の例では \scriptsize となる。

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))

# Below is to reduce font size in code block
# \tiny         5pt
# \scriptsize   7pt
# \footnotesize 8pt
# \small        9pt
#


from sphinx.highlighting import PygmentsBridge
from pygments.formatters.latex import LatexFormatter

class CustomLatexFormatter(LatexFormatter):
    def __init__(self, **options):
        super(CustomLatexFormatter, self).__init__(**options)
        self.verboptions = r"formatcom=\scriptsize"

PygmentsBridge.latex_formatter = CustomLatexFormatter

1.3.2. jupyter-notebookとの連携

conf.py の先頭の方に以下を挿入する。

# for jupyter-notebook

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

from recommonmark.transform import AutoStructify

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

また、 # -- General configuration で extensions の後ろにコメントアウトしているのを外す

source_suffix = ['.rst', '.md']
# source_suffix = '.rst'

最後に、 index.rst の中の:

.. toctree::
    :numbered:

    jupyter

の下に jupyter-notbook のファイル名を入れておく。 具体的な文章作成の例 のtoctreeの項を参照のこと

1.3.3. blockdiag,graphvizとmathjaxの設定

jupyter-notebookとの連携も対応させておく。

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.mathjax',
    'sphinxcontrib.blockdiag',
    'sphinxcontrib.actdiag',
    'sphinx.ext.graphviz',
    'nbsphinx',
]

1.3.4. html出力のための設定

# -- Options for HTML output ----------------------------------------------

import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

1.3.5. latex出力のための詳細設定

以下はlatex出力の設定のコアとなる部分のコードである。

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
'pointsize': '12pt',


# geometry
'geometry': '\\usepackage[vmargin=2cm, hmargin=2cm]{geometry}',
#babel
'babel': '\\usepackage[japanese]{babel}',

# Additional stuff for the LaTeX preamble.
#\\usepackage[top=20truemm,bottom=20truemm,left=20truemm,right=20truemm]{geometry}

'preamble': r'''

\setlength\parindent{1zw}
\renewcommand{\baselinestretch}{0.8}

\usepackage[version=4]{mhchem}
\usepackage{siunitx}
\usepackage{chemfig}

\makeatletter
\renewcommand{\maketitle}{
\begin{center}
    {\Large \@title} \par
\end{center}
\begin{flushright}
    \@date \hspace{3zw} \@author \par
\end{flushright}
}

\@addtoreset{equation}{section} \def\theequation{\thesection.\arabic{equation}}

\makeatother

\pagestyle{plain}
\thispagestyle{plain}

'''
}

latex_elements['tableofcontents'] = r'''
\pagenumbering{arabic} % page numbering as arabic
\pagestyle{normal} % page set to normal
'''

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'output.tex', u'NewTitle',
    u'Fujisawa', 'howto'),
]

# Numbering tables and figures
numfig=True
numfig_secnum_depth=2

218行目

ペーパーサイズ

221行目

フォントサイズ

225行目

geometryパッケージ　上下左右の余白調整用

227行目

日本語用パッケージ。無くても大丈夫

preamble部 ここが重要

234行目

段落の始めの字下げ

235行目

行間を縮めている

236行目

表紙部分の設定コマンド

237行目

mhchemパッケージ　化学式等に使用する

238行目

siunitxパッケージ 単位混在の数値表記に使用する

239行目

chemfigパッケージ 化学構造式の描画に使用する

241-250行目

タイトル行をコンパクト化

252-253行目

ページ番号をつける

261-264行目

目次の削除

271行目

文章スタイルの選択。ここでは簡潔なメモ用の howto を使用

275行目

表、図の自動連番

276行目

表、図の自動連番のフォーマット

重要

古いバージョンのsphinxを再コンパイルする際の注意

新しいバージョンのsphinxでは

renewcommand{maketitle}{

ではなく

renewcommand{sphinxmaketitle}{

と変更しなくてはならない。

1.4. windowsの場合の sphinx の文章作成環境の設定

windowsの場合はlinuxと若干異なる