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

## 参考文献

- Markdown の文法: [CommonMark](http://commonmark.org/help/)
- [Overview — Sphinx 1.8.0+ documentation](http://www.sphinx-doc.org/)
- [recommonmark — Recommonmark 0.4.0 documentation](https://recommonmark.readthedocs.io/)
- [トップページ | Read the Docs](https://readthedocs.org/)
- [blockdiag - simple diagram images generator — blockdiag 1.0 documentation](http://blockdiag.com/)

## Sphinx インストール手順

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

### 手順詳細

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

## チュートリアル

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

    ```diff
    --- 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)
    ```

1. HTML ファイルを作成する: `build\html` に HTML ファイルが作成される。
   - `> make html`
1. 以下の内容を `source\test.md` というファイル名で作成する。

    ```md:source\test.md
    # テスト

    これはテスト文書です。

    以上。
    ```

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

    ```diff
    --- 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
    ```

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

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

Markdown を編集するだけなら, [Visual Studio Code](http://code.visualstudio.com/) でも OK.

1. [サクラエディタ向け Markdown シンタックスハイライト設定](https://qiita.com/ryo-sato/items/4cbfe057836c14293def) を参考に設定する。

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

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

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

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

## 参考: Markdown で表を作る場合

Markdown は表がサポートされていない。
[Support tables · Issue #3 · rtfd/recommonmark · GitHub](https://github.com/rtfd/recommonmark/issues/3) によると, `eval_rst` を使うのも有りとのこと。
具体例は [eval_rst table - Google 検索](https://www.google.com/search?q=eval_rst+table) などで検索すること。

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

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

```html: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>
```

どっとはらい。