sphinx-markdown-parser 0.1.6

Contents

• API Reference

• AutoStructify Component

Getting Started

To use sphinx-markdown-parser inside of Sphinx only takes 2 steps. First you install it:

pip install sphinx-markdown-parser

Then add this to your Sphinx conf.py:

# for MarkdownParser
from sphinx_markdown_parser.parser import MarkdownParser

def setup(app):
    app.add_source_suffix('.md', 'markdown')
    app.add_source_parser(MarkdownParser)
    app.add_config_value('markdown_parser_config', {
        'auto_toc_tree_section': 'Content',
        'enable_auto_doc_ref': True,
        'enable_auto_toc_tree': True,
        'enable_eval_rst': True,
        'enable_inline_math': True,
        'enable_math': True,
    }, True)

# for CommonMarkParser
from recommonmark.parser import CommonMarkParser

def setup(app):
    app.add_source_suffix('.md', 'markdown')
    app.add_source_parser(CommonMarkParser)
    app.add_config_value('markdown_parser_config', {
        'auto_toc_tree_section': 'Content',
        'enable_auto_doc_ref': True,
        'enable_auto_toc_tree': True,
        'enable_eval_rst': True,
        'enable_inline_math': True,
        'enable_math': True,
    }, True)

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

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

# At the bottom of conf.py
def setup(app):
    app.add_config_value('markdown_parser_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

Development

You can run the tests by running tox in the top-level of the project.

We are working to expand test coverage, but this will at least test basic Python 2 and 3 compatability.

Why a bridge?

Many python tools (mostly for documentation creation) rely on docutils. But docutils only supports a ReStructuredText syntax.

For instance this issue and this StackOverflow question show that there is an interest in allowing docutils to use markdown as an alternative syntax.

Why another bridge to docutils?

recommonmark uses the python implementation of CommonMark while remarkdown implements a stand-alone parser leveraging parsley.

Both output a `docutils document tree <http://docutils.sourceforge.net/docs/ref/doctree.html>`__ and provide scripts that leverage docutils for generation of different types of documents.

Acknowledgement

recommonmark is mainly derived from remarkdown by Steve Genoud and leverages the python CommonMark implementation.

It was originally created by Luca Barbato, and is now maintained in the Read the Docs (rtfd) GitHub organization.