recommonmark [1]¶

备注

本插件是让markdown文件和rst文件可以接合使用。实践感觉还行，基本能用。

官网 [2]

说明:

recommonmark is a Docutils bridge to CommonMark-py
a Python package for parsing the CommonMark Markdown flavor

安装:

pip install recommonmark

本教程用到的extensions:

sphinx-ext-autosectionlabel

基础使用¶

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

# for Sphinx-1.3
from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

备注

This allows you to write both .md and .rst files inside of the same project.

Links¶

使用:

extensions = [
    # Auto-generate section labels.
    'sphinx.ext.autosectionlabel',
]

# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
# rather than 'path/to/file:heading'
autosectionlabel_prefix_document = True

实例file_1.md:

<!-- path/to/file_1.md -->

# Title

## My Subtitle

实例file_2.md:

<!-- file_2.md -->

[My Subtitle][]

[My Subtitle]: <path/to/file_1:My Subtitle>

可以使用:

.. toctree::

   link
   second

AutoStructify¶

# At top on conf.py (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'

# 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)