LoginSignup
0
2

More than 3 years have passed since last update.

@iisaka51(Goichi (Iisaka) Yukawa)

sphinx-quickstart が面倒になり代替コマンドを作ってみたらストレスがなくなった

Last updated at Posted at 2020-09-18

はじめに

sphinx はドキュメント作成が非常に便利です。
ただし、sphinx-quickstart は基本的にはリターンだけでよいのですが、
もう少しだけなんとかならないのかと思っていました。
sphinx を使えば使うほど、この面倒だと思う気持ちが強くなり、
sphinx-express なるものを作ってみました。

独り言： 力技です。かっこよくも美しくもないスクリプトです。
オプション解析のために typer モジュールを使っているので Python3.6以降で期待どおりに動いてくれます。

依存モジュール

github からクローンしてインストールしてください。

$ git clone https://github.com/iisaka51/sphinx-express.git
$ cd sphinx-express
$ python setup.py install

使い方

初回は --setup オプションを与えて実行します。

$ sphinx-express.py --setup

You should install follows packages.
python -m pip install sphinx-rtd-theme sphinx-charts pallets_sphinx_themes sphinxcontrib-runcmd sphinxcontrib-napoleon

your configfile: /Users/goichiiisaka/.sphinx/quickstartrc
your templatedir: /Users/goichiiisaka/.sphinx/templates/quickstart
quickstart templates of sphinx into your templatedir.

これで、$HOME/.sphinx 以下に
quickstartrc と sphinx が持っている テンプレートファイルをコピーしてくれます。

$ tree  ~/.sphinx/
/Users/goichiiisaka/.sphinx/
├── quickstartrc
└── templates
    └── quickstart
        ├── Makefile.new_t
        ├── Makefile_t
        ├── conf.py_t
        ├── make.bat.new_t
        ├── make.bat_t
        └── master_doc.rst_t

2 directories, 7 files

~/.sphinx/quickstartrc はデフォルトでは次のようにしています。


sep: true
language: ja
suffix: .rst
master: index
makefile: true
batchfile: true
autodoc: true
doctest: false
intersphinx: false
todo: false
coverage: false
imgmath: true
mathjax: true
ifconfig: true
viewcode: true
project: sample
version: 0.0.1
release: 0.0.1
lang: ja
make_mode: true
ext_mathjax: true
extensions:
- pallets_sphinx_themes
- sphinx_rtd_theme
- sphinx.ext.autodoc
- sphinx.ext.mathjax
- sphinx.ext.autosectionlabel
- sphinxcontrib.blockdiag
- sphinxcontrib.seqdiag
- sphinxcontrib.blockdiag
- sphinxcontrib.nwdiag
- sphinxcontrib.rackdiag
- sphinxcontrib.httpdomain
- sphinxcontrib.runcmd
- recommonmark
mastertocmaxdepth: 2
project_underline: ======
  • sep: ソースと生成ドキュメントを別ディレクトリで管理するか bool
  • dot: templates などで使用する接頭子の定義 ()
  • project: project name
  • author: 著作者
  • version: バージョン番号
  • release: リリース番号
  • language: ドキュメントで使用する言語
  • suffix: ソースの拡張子
  • master: マスタードキュメント名
  • extensions: 使用するエクステンション
  • makefile: Makefileのタイプ bool
  • batchfile: make.bat を生成するか bool

後はこのファイルを修正すれば、
shpinx-express.py が読み込んでくれるので、
コマンド一発で sphinx のプロジェクトディレクトリが整います。

$ sphinx-express sample
Welcome to the Sphinx 3.2.1 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: sample

Creating file /Users/goichiiisaka/docs/sample/source/conf.py.
Creating file /Users/goichiiisaka/docs/sample/source/index.rst.
Creating file /Users/goichiiisaka/docs/sample/Makefile.
Creating file /Users/goichiiisaka/docs/sample/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/goichiiisaka/docs/sample/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.

sphinx のプロジェクトディレクトリは、なければ作成するようにしています。
project のデフォルトは、プロジェクトディレクトリになります。
author はデフォルトでos.getlogin() で取得したログインユーザ名です。

$ sphinx-express --help
Usage: sphinx-express [OPTIONS] PROJECT_DIR

  Create required files for a Sphinx project.

Arguments:
  PROJECT_DIR  [required]

Options:
  -p, --project PROJECT_NAME      project name.  default is basename of
                                  PROJECT_DIR.

  -a, --author AUTHOR_NAME        author name. default is "goichiiisaka"
                                  [default: goichiiisaka]

  -v, --ver VERSION               version of project.  [default: 0.0.1]
  -l, --lang LANG                 document language.  [default: ja]
  -t, --templatedir TEMPLATE_DIR  template directory for template files.
                                  [default: /Users/goichiiisaka/.sphinx/templa
                                  tes/quickstart]

  -d, --define NAE=VALUE          define a template variable.
  -c, --configfile CONFIG_FILEPATH
                                  sphinx-express configfile.  [default:
                                  /Users/goichiiisaka/.sphinx/quickstartrc]

  -N, --new                       Ignore least configures.  [default: False]
  --setup                         Copy templates and exit.  [default: False]
  --version                       Show version and exit.  [default: False]
  --help                          Show this message and exit.

テンプレート

~/.sphinx/templates/quickstart/conf.py_t は、
コピーするだけでなく次のような地味な修正をしています。

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

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#

# Avilable Themes: alabaster
{% set default_theme="alabaster" %}
{%- if 'sphinx_rtd_theme' in extensions -%}
# sphinx_rtd_theme
{% set default_theme="sphinx_rtd_theme" %}
{%- endif -%}
{%- if 'pallets_sphinx_themes' in extensions -%}
# babel, click, flask, jinja, platter, pocoo, werkzeug
{% set default_theme="flask" %}
{%- endif -%}
#
html_theme = "{{ default_theme }}"


{%- if 'sphinxcontrib.seqdiag' in extensions %}
# -- Options for seqdiag output -------------------------------------------

# curl -O https://ja.osdn.net/projects/ipafonts/downloads/51868/IPAfont00303.zip
import os
basedir = os.path.abspath(os.path.dirname(__file__))
seqdiag_fontpath = basedir + '/_fonts/IPAfont00303/ipagp.ttf'
seqdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.nwdiag' in extensions %}
# -- Options for nwdiag output --------------------------------------------

nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.blockdiag' in extensions %}
# -- Options for blockdiag output ------------------------------------------

blockdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.actdiag' in extensions %}
# -- Options for actdiag output --------------------------------------------

actdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.httpdomain' in extensions %}
# -- Options for httpdomain output ------------------------------------------

# List of HTTP header prefixes which should be ignored in strict mode:
http_headers_ignore_prefixes = ['X-']

# Strips the leading segments from the endpoint paths
# by given list of prefixes:
# http_index_ignore_prefixes = ['/internal', '/_proxy']

# Short name of the index which will appear on every page:
# http_index_shortname = 'api'

# Full index name which is used on index page:
# http_index_localname = "My Project HTTP API"

# When True (default) emits build errors when status codes,
# methods and headers are looks non-standard:
http_strict_mode = True
{%- endif %}


{%- if 'recommonmark' in extensions %}
# -- Options for recommonmark output ----------------------------------------
import recommonmark
from recommonmark.transform import AutoStructify

# At the bottom of conf.py
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)
{%- endif %}

小技

あまり使うことがないかもですが、
~/,sphinx/quickstartrc に variables を定義すると、
テンプレートファイルで使用している jinja2 の変数に値をセットすることができます。

variables:
- NAME=VALUE
0
2
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
2