Unable to get Recommonmark to Work

xobs commented 5 years ago

Background

I'm trying to enable users to write documentation in the more common Markdown format, rather than forcing them to learn reStructured Text. As such, I'd like to use something such as recommonmark to enable this.

The AutoStructify documentation says that "AutoStructify makes it possible to write your documentation in Markdown, and automatically convert this into rST at build time". I'm trying to do this at build time, but this doesn't appear to be happening.

Configuration

My configuration is based on the recommended configuration at https://github.com/rtfd/recommonmark/blob/master/docs/conf.py (linked to from https://recommonmark.readthedocs.io/en/latest/index.html#autostructify):

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

project = 'LiteX SoC Project'
copyright = '2019, Anonymous'
author = 'Anonymous'
extensions = [
    'sphinxcontrib.wavedrom',
    "recommonmark",
]
templates_path = ['_templates']
exclude_patterns = []
offline_skin_js_path = "https://wavedrom.com/skins/default.js"
offline_wavedrom_js_path = "https://wavedrom.com/WaveDrom.js"
html_theme = 'alabaster'
html_static_path = ['_static']

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

# 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',
        'enable_eval_rst': True,
        'enable_auto_doc_ref': True,
    }, True)
    app.add_transform(AutoStructify)

Then in my documentation tree I have the following in a file called usb.rst:

How to Use
----------

.. include:: D:\Code\Fomu\foboot\hw\deps\valentyusb\valentyusb\usbcore\cpu\howto.md

Issue

This doesn't cause howto.md to be rendered as Markdown, despite the fact that .md files are supposed to be rendered as Markdown. Instead it gets included verbatim, without getting converted at build-time.

s-weigand commented 5 years ago

You need to have the *.md file or a symlink to it (see here) in the same folder as your conf.py. When that is done include it in your toctree as you would a *.rst file (howto).

xobs commented 5 years ago

My mistake. I seem to have misunderstood how recommonmark works.

My initial assumption was that it maps filename endings to text processors, and by providing an include directive that would let me mix markdown and reStructured Text in one file.

It appears as though this isn't how it works, and normally you can't mix formats within a single document.

I've since switched to use m2r which does allow for this.

readthedocs / recommonmark