Skip to content

Sphinx#

  • sphinx は Python のドキュメント生成ツール
  • reStructredText で記述されたファイルをHTML/PDFなど様々形式で出力可能
  • rst の書方はMaterial for Sphinxrst Cheatsheetを参考に

Getting Started#

Sphinx をインストール

$ pip install Sphinx
  • ファイルを格納する任意のディレクトリを作成し、移動
  • sphinx-quickstart　で必要なファイルを生成 
    $ mkdir work
$ cd work
$ sphinx-quickstart

上記実行後、いくつか質問が表示されるので回答していく。内容は以下の通り

質問 質問の意味 回答例
Separate source and build directories (y/n) [n]: ソースファイルのフォルダーとビルドして作成されるファイルなどを別々のフォルダーにしますか n
Project name: プロジェクト名を入力してください Knowledge
Author name(s): 作成者名を入力してください Taro
Project release []: リリース番号（バージョン番号）を入力してください 1
Project language [en]: 言語を指定してください ja

上記手順後、ディレクトリに以下ファイルが生成される。(Separate source and build directories (y/n) [n]でnを選択した場合)

ファイル名 説明
conf.py ビルド設定ファイル
index.rst .reST記法で書かれた原稿の雛形
make.bat ビルドスクリプト（Windows）
Makefile ビルドスクリプト（その他環境用）
_build 成果物の出力ディレクトリ
_static 静的ファイルを配置するディレクトリ
_templates HTMLテンプレート用ディレクトリ
  • 原稿となるドキュメントを作成する
  • デフォルトでindex.rstが用意されているが rst記法は面倒なので 後述の設定にて markdown を使用できるようにして、Markdown記法にて対応
  • doc ディレクトリを作成し、その中でドキュメントを管理する方法がおすすめ
  • doc ディレクトリ直下にはindex.mdを配置して目次管理

プロジェクト直下のディレクトリで以下コマンド入力して ドキュメントを ビルドする

$ make html

実行後は_buildディレクトリにファイルが生成される

設定ファイル:conf.py#

Markdown を使う#

Markdown ベースのドキュメントをサポートするために、Sphinx はMyST-Parserを使用できます。 MyST-Parser は、 CommonMark Markdown フレーバーを解析するための Python パッケージであるmarkdown-it-pyへのブリッジです。 引用: sphinx - Markdown

  1. MyST-Parserをインストール 

    pip install --upgrade myst-parser

  2. conf.py 内の extensions に　myst_parserを 追加

    conf.py
    # import sys, os
# 
# sys.path.append(os.path.abspath('sphinxext'))

extensions = ['myst_parser']

Info

MyST-Parser は Sphinx 2.1 以降でサポート

  1. source_suffix に　.md 拡張子を追加
source_suffix = {
    '.md': 'markdown',
}

テーマを変更する#

option

conf.py
html_theme = 'sphinx_material'

# Material theme options (see theme.conf for more information)
html_theme_options = {

    # Set the name of the project to appear in the navigation.
    'nav_title': 'Project Name',

    # Set you GA account ID to enable tracking
    'google_analytics_account': 'UA-XXXXX',

    # Specify a base_url used to generate sitemap.xml. If not
    # specified, then no sitemap will be built.
    'base_url': 'https://project.github.io/project',

    # Set the color and the accent color
    'color_primary': 'blue',
    'color_accent': 'light-blue',

    # Set the repo location to get a badge with stats
    'repo_url': 'https://github.com/project/project/',
    'repo_name': 'Project',

    # Visible levels of the global TOC; -1 means unlimited
    'globaltoc_depth': 3,
    # If False, expand all TOC entries
    'globaltoc_collapse': False,
    # If True, show hidden TOC entries
    'globaltoc_includehidden': False,
}

docstring から ドキュメント生成#