Markdownによる記述

Sphinxはデフォルトで、reStructuredText (reST)というマークアップ言語で記述しますが、Markdownやその拡張であるMySTでも記述できます。

Markdown（MyST）を使うには、Sphinx拡張の MyST-Parser をインストールします。

MyST-Parserのインストール

$ python -m pip install myst-parser

次に conf.py の extensions のリストに 'myst_parser' を追加します。

conf.py

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'sample'
copyright = '2024, your_name'
author = 'your_name'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ['myst_parser']

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

Markdownでテキストファイルを記述します、ここでは hello.md というファイルを作成します。

hello.md

# はじめてのSphinx

[Markdown](https://daringfireball.net/projects/markdown/)記法にしたがって記述できます。

## リスト

順序なしリスト

- グー
- チョキ
- パー

順序付きリスト

1. ウォード
2. トラウト
3. 大谷

## ブロッククォート

> 引用
>> ネストされた引用

index.rst に hello.md をtoctreeに追加します。toctreeとは複数の文書を構造化するために使われます。toctreeでは、章-節などの複雑な構造をもつ文書を作成できますが、ここではtoctreeに記述したファイルの順番に文書が出力されると覚えておいてください。toctreeにファイルを追加するときに、ファイルの拡張子は記述しません。

index.rst

.. sample documentation master file, created by
   sphinx-quickstart on Sat Jan 13 14:30:31 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sample's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   hello

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

HTMLにビルドします、HTMLに hello.md の内容が追加されます。

HTMLへビルド

$ make html