conf.pyテンプレート作成

created at 2019-08-12 17:11+0900

conf.pyの変更をテンプレート化して、Sphinxプロジェクトを作成する

conf.py_tファイル作成

conf.pyファイルのテンプレートとなるconf.py_tファイルをソースからコピーする

cd ~/Documents/XDOCS/sphinx && ls -la && pwd
mkdir ../_templates
find $(pipenv --venv) -name "conf.py_t" -print0 | xargs -J % -0 cp % ../_templates/

conf.py_tファイルの内容はjinja2テンプレートとなっている。

Template Designer Documentation https://jinja.palletsprojects.com/en/master/templates/

conf.py_tを編集

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# 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.
#
{% if theme_name == 'bootstrap' -%}
import sphinx_bootstrap_theme
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
{% else -%}
{% if append_syspath -%}
import os
import sys
sys.path.insert(0, {{ module_path | repr }})
{% else -%}
# import os
# import sys
{% if module_path -%}
# sys.path.insert(0, {{ module_path | repr }})
{% else -%}
# sys.path.insert(0, os.path.abspath('.'))
{% endif -%}
{% endif %}
{% endif -%}

# -- Project information -----------------------------------------------------

project = {{ project | repr }}
copyright = {{ copyright | repr }}
author = {{ author | repr }}

{%- if version %}

# The short X.Y version
version = {{ version | repr }}
{%- endif %}
{%- if release %}

# The full version, including alpha/beta/rc tags
release = {{ release | repr }}
{%- endif %}


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
{%- for ext in extensions %}
    '{{ ext }}',
{%- endfor %}
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['{{ dot }}templates']

{% if suffix != '.rst' -%}
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = {{ suffix | repr }}

{% endif -%}
{% if master != 'index' -%}
# The master toctree document.
master_doc = {{ master | repr }}

{% endif -%}
{% if language -%}
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = {{ language | repr }}

{% endif -%}
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [{{ exclude_patterns }}]


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

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = '{{ theme_name | default('alabaster') }}'
{% if last_updated_fmt is defined %}
html_last_updated_fmt = '{{ last_updated_fmt }}'
{% endif %}
{%- if enable_sidebar %}
html_sidebars = {'**': ['localtoc.html','globaltoc.html','relations.html', 'sourcelink.html', 'searchbox.html']}
{% endif %}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['{{ dot }}static']
{%- if extensions %}


# -- Extension configuration -------------------------------------------------
{%- endif %}
{%- if 'sphinx.ext.intersphinx' in extensions %}

# -- Options for intersphinx extension ---------------------------------------

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
    'python':('https://docs.python.org/3/', None),
    'conoha':('../../../conohaVps_2019/build/html/', '../../conohaVps_2019/build/html/objects.inv'),
    'sphinx':('../../../sphinx/build/html/', '../../sphinx/build/html/objects.inv'),
}
{%- endif %}
{%- if 'sphinx.ext.todo' in extensions %}

# -- Options for todo extension ----------------------------------------------

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
{%- endif %}


{% if theme_name == 'bootstrap' -%}
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
    'navbar_class': "navbar navbar-inverse",
    'bootswatch_theme': "flatly",
    'globaltoc_depth': 2,
}
{%- endif %}
{%- if 'sphinxcontrib.blockdiag' in extensions %}
blockdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
{%- endif %}
{%- if 'sphinxcontrib.seqdiag' in extensions %}
seqdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
{%- endif %}
{%- if 'sphinxcontrib.actdiag' in extensions %}
actdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
{%- endif %}
{%- if 'sphinxcontrib.nwdiag' in extensions %}
nwdiag_fontpath = ['../../fonts/ipaexg.ttf','../../fonts/ipaexm.ttf']
{%- endif %}

{%- if 'sphinx.ext.graphviz' in extensions %}
graphviz_dot = '/usr/local/bin/dot'
{%- endif %}
{%- if 'sphinxcontrib.plantuml' in extensions %}
plantuml = 'java -jar ~/Applications/plantuml/plantuml.jar'
{%- endif %}

intersphinx_mapping オプションの(ターゲット, インベントリ) というタプルの設定値を相対パスで記述する場合、

  • 'ターゲット'は参照元プロジェクトのHTMLドキュメントルートから見た参照先プロジェクトのHTMLドキュメントルートへの相対パス

  • 'インベントリ'は参照元プロジェクトのソースディレクトリから見た参照先プロジェクトのインベントリへの相対パス

を書くと思われる。

変更内容確認

find $(pipenv --venv) -name "conf.py_t" -print0 | xargs -J % -0 diff % ../_templates/conf.py_t

Sphinxプロジェクト作成

テンプレートディレクトリを指定してSphinxプロジェクトを作成する

sphinx-quickstart --quiet -p sphinx -a r-square.net -v 2019 -r 0.1 -l ja --sep \
    --ext-todo --ext-intersphinx --ext-ifconfig --ext-viewcode --makefile --no-batchfile -t ../_templates \
    --extensions='sphinxcontrib.blockdiag,sphinxcontrib.seqdiag,sphinxcontrib.actdiag,sphinxcontrib.nwdiag' \
    --extensions='sphinx.ext.graphviz' --extensions='sphinxcontrib.plantuml' \
    -d theme_name='bootstrap' -d last_updated_fmt='%Y-%m-%d %H:%M:%S JST' -d enable_sidebar=1

オプションの説明

--extensions=ext

拡張機能を追加する。sphinx.ext.**とかsphinxcontrib.**とか。カンマ区切りでリストを渡せる。また複数指定可能。

-d NAME=VALUE

conf.py_t内のjinja2テンプレート変数に値を設定する。 デフォルトのconf.py_tでは -d append_syspath=True -d module_path=/path/to/module/ を指定すると、conf.pyにimportが記述されるらしい (sphinx.ext.autodoc拡張を有効にしてdocstringを漁る場合に必要なのか?)。

-d theme_name=str

今回conf.py_tに追加した設定。Sphinxテーマ名(html_theme)を指定する。

-d last_update_fmt=str

今回conf.py_tに追加した設定。更新日時の日付フォーマット(html_last_updated_fmt)を指定する。パラメータ自体を指定しない場合は表示しない。 last_update_fmtが空文字列の場合はlanguage設定のデフォルト値になる。日付フォーマットで%Zを指定すると'協定世界時'と表示される。でも日時はJSTが表示されてる。

-d enable_sidebar=int

今回conf.py_tに追加した設定。1の場合サイドバーを有効にする。

html_sidebars = {'**': ['localtoc.html','globaltoc.html','relations.html', 'sourcelink.html', 'searchbox.html']}

see Sphinxプロジェクト作成.

マスターファイルindex.rst を編集

toctree にコンテンツファイル追記

htmlビルド

conf.py内の設定値を変更するにはSPHINXOPTSを設定してmakeする。

(export SPHINXOPTS="-E -D html_last_updated_fmt='%Y-%m-%d %H:%M:%S JST' -D graphviz_dot='/usr/local/bin/dot' -D plantuml='java -jar ~/Applications/plantuml/plantuml.jar'";make html)