試しに Markdown で Sphinx ドキュメント作成

Sphinx はドキュメントを作成するためのツールであり reStructuredText を採用しています。

reStructuredText は Markdown と同様な軽量マークアップ言語のひとつで実際に使ってみるとなかなか使いやすいですが、Markdown と比べると Sphinx 以外では汎用的に採用されておりません。

そこで Sphinx で reStructuredText ではなく Markdown を使ってドキュメントを作成できるようにしてみました。

下にも書いてますが、何かワーニングが出ましたが一応 Markdown でドキュメントを書いて html に変換できました。

環境

• Ubuntu 18.04.4 LTS (Windows10 WSL)

インストール

pipenv で Sphinx をインストールするのでまずは pipenv をインストール

$ sudo apt install pipenv

sphinx インストール用のディレクトリを作成して移動

$ mkdir /some/where/sphinx
$ cd /some/where/sphinx/

virtual environment 作成

$ pipenv --python $(which python3)

Sphinx インストール

$ pipenv install sphinx

Markdownパーサー recommonmark をインストール

$ pipenv install recommonmark

pipenv シェル起動

Sphinx をインストールした virtual environment でシェルを起動しました。

virtual environment に起動

$ cd /some/where/sphinx/

pipenv シェル起動

$ pipenv shell

Sphinx ドキュメントプロジェクト作成

上に描いた「pipenv シェル起動」を実行した状態で以下をやりました。

プロジェクト用のディレクトリを作成して移動

$ mkdir /some/where/document
$ cd /some/where/document/

プロジェクトファイル作成

$ sphinx-quickstart

いろいろ聞いてくるので以下のように入力してみました。

> Separate source and build directories (y/n) [n]: n
> Project name: test-markdown
> Author name(s): Nezuppo
> Project release []:
> Project language [en]: ja

以下のうようにディレクトリとファイルが作成されました。

$ tree -aF
.
├── Makefile
├── _build/
├── _static/
├── _templates/
├── conf.py
├── index.rst
└── make.bat

3 directories, 4 files

Markdown が使えるようにプロジェクトを設定

まずは conf.py を修正するのでバックアップをとる

$ cp conf.py{,.org}

以下のようになるよう、conf.py を修正。なお本題とは関係ありませんが好みで html_theme を bizstyle に変更しました。

$ diff -u conf.py{.org,}
--- conf.py.org 2020-05-10 14:51:51.652409000 +0900
+++ conf.py     2020-05-10 15:30:52.760240100 +0900
@@ -28,6 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'recommonmark'
 ]

 # Add any paths that contain templates here, relative to this directory.
@@ -51,9 +52,17 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'bizstyle'

 # 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 = ['_static']
+
+
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md' : 'markdown',
+}

Markdown でドキュメント作成

index.rst のファイル名を index.md に変更

$ mv index.rst index.md

この時点で index.md の中身はデフォルトで用意されたサンプルの reStructuredText なので、不要であることを確認して中身を削除し Markdown に書き換え

html に変換

$ make html

以下のワーニングが出ました。。。

/home/worker/.local/share/virtualenvs/sphinx-5rYzJHjd/lib/python3.6/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))

が、とりあえず _build/html が作成され、ブラウザで index.html を確認できました。

参考

• https://www.sphinx-doc.org/ja/master/usage/markdown.html