Windows で Markdown から Sphinx 文書を作る方法のメモ

参考文献

• Markdown の文法: CommonMark
• Overview — Sphinx 1.8.0+ documentation
• recommonmark — Recommonmark 0.4.0 documentation
• トップページ | Read the Docs
• blockdiag - simple diagram images generator — blockdiag 1.0 documentation

Sphinx インストール手順

• Overview — Sphinx 1.8.0+ documentation
  • 画面上部の Get it をクリックする: Installing Sphinx ページに遷移する。
    • 目次の Windows をクリックする。
      • 2018/06/08 時点で, Python 3 is recommended. と記載されている。

手順詳細

1. Python.org より Python 3.x をインストールする。
   • 3 系の最新版であれば OK.
   • Windows の 64 ビット版であれば, Windows x86-64 executable installer をダウンロードする。
   • インストール先は C:\Python36 とする。
2. (Windows 10 の場合) スタート - 設定 より 環境変数 と検索し, 環境変数を編集 をクリックする。
3. C:\Python36 と C:\Python36\Scripts を追加する。
4. コマンドプロンプトを開き, 以下のコマンドを実行, Sphinx をインストールする。
   • pip install -U sphinx recommonmark sphinx_rtd_theme sphinxcontrib-blockdiag sphinxcontrib-seqdiag sphinxcontrib-actdiag sphinxcontrib-nwdiag

チュートリアル

1. コマンドプロンプトを開き, 文書を格納するフォルダーに移動, ひな形を作成する。
   • > mkdir sphinx
   • > cd sphinx
   • > sphinx-quickstart
2. 以下の通り設定し, これ以外は全て Enter キーを空打ちする。
   • Separate source and build directories (y/n) [n] は y とする。
   • Project name は文書名を入力する: テスト文書 などの 2 バイト文字でも OK.
   • Author name(s) は著者名を入力する: Ryo Sato などの個人名でも良いし, 組織名でも OK.
   • Project language [en] は ja とする。

3. source\conf.py を以下の通りに編集する。

   --- conf_original.py    2018-06-08 13:46:29.651054900 +0900
   +++ conf.py 2018-06-08 13:54:40.174860100 +0900
   @@ -16,6 +16,11 @@
    # import sys
    # sys.path.insert(0, os.path.abspath('.'))
   
   +# At top on conf.py (with other import statements)
   +import recommonmark
   +from recommonmark.transform import AutoStructify
   +from recommonmark.parser import CommonMarkParser
   +
   
    # -- Project information -----------------------------------------------------
   
   @@ -39,6 +44,12 @@
    # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
    # ones.
    extensions = [
   +    'sphinxcontrib.blockdiag',
   +    'sphinxcontrib.seqdiag',
   +    'sphinxcontrib.actdiag',
   +    'sphinxcontrib.nwdiag',
   +    'sphinxcontrib.rackdiag',
   +    'sphinxcontrib.packetdiag'
    ]
   
    # Add any paths that contain templates here, relative to this directory.
   @@ -47,8 +58,11 @@
    # The suffix(es) of source filenames.
    # You can specify multiple suffix as a list of string:
    #
   -# source_suffix = ['.rst', '.md']
   -source_suffix = '.rst'
   +source_parsers = {
   +    '.md': CommonMarkParser,
   +}
   +source_suffix = ['.rst', '.md']
   +# source_suffix = '.rst'
   
    # The master toctree document.
    master_doc = 'index'
   @@ -74,7 +88,7 @@
    # The theme to use for HTML and HTML Help pages.  See the documentation for
    # a list of builtin themes.
    #
   -html_theme = 'alabaster'
   +html_theme = 'sphinx_rtd_theme'
   
    # Theme options are theme-specific and customize the look and feel of a theme
    # further.  For a list of options available for each theme, see the
   @@ -152,4 +166,12 @@
        (master_doc, 'sphinx', 'テスト文書 Documentation',
         author, 'sphinx', 'One line description of project.',
         'Miscellaneous'),
   -]
   \ No newline at end of file
   +]
   +
   +# 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)
   

4. HTML ファイルを作成する: build\html に HTML ファイルが作成される。

   • > make html

5. 以下の内容を source\test.md というファイル名で作成する。

   source\test.md

   # テスト
   
   これはテスト文書です。
   
   以上。
   

6. source\index.rst を以下の通りに編集する。ファイルの拡張子 (.md) は不要。

   --- index_original.rst  2018-06-08 14:01:45.500715000 +0900
   +++ index.rst   2018-06-08 14:02:08.688867000 +0900
   @@ -10,6 +10,8 @@
       :maxdepth: 2
       :caption: Contents:
   
   +   test
   +
   
    Indices and tables
   

7. 再度, HTML ファイルを作成する: build\html に HTML ファイルが追加, 更新される。

   • > make html

サクラエディタ向け Markdown 設定 (任意)

Markdown を編集するだけなら, Visual Studio Code でも OK.

1. サクラエディタ向け Markdown シンタックスハイライト設定 を参考に設定する。

nyagos インストール手順 (任意)

1. NYAOS.ORG にアクセスし, 右ペインの NYAOS 4.x (NYAGOS) をクリックする。
2. Documents - Install をクリックする。
3. Install - Release をクリックする。
4. zip ファイルをダウンロード, 展開する。
5. 上記と同様, nyagos.exe への PATH を登録する。

Pandoc インストール手順 (任意)

1. Pandoc にアクセスし, 左ペインの Installing をクリックする。
2. Windows セクションより, download page をクリックする。
3. (例えば) zip 版をダウンロード, 展開する。
4. 上記と同様, pandoc.exe への PATH を登録する。

参考: Markdown で表を作る場合

Markdown は表がサポートされていない。
Support tables · Issue #3 · rtfd/recommonmark · GitHub によると, eval_rst を使うのも有りとのこと。
具体例は eval_rst table - Google 検索 などで検索すること。

参考: Makefile と同じフォルダーに配置する index.html

わざわざ build フォルダーの下にアクセスするのが面倒な場合に。

index.html

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="refresh" content="0; url=build/html/index.html" />
    <title>ジャンプしますよ!</title>
  </head>
  <body>
    <p>ジャンプしますよ!</p>
  </body>
</html>

どっとはらい。