README.rst

sphihxcontrib_markdown

experimental implementation to use markdown as input of Sphinx.

How to install

1. install remarkdown

   $ pip install https://github.com/sgenoud/remarkdown/archive/master.zip
   $ curl -LO https://raw.githubusercontent.com/sgenoud/remarkdown/master/remarkdown/markdown.parsley
   $ mv markdown.parsley lib/python2.7/site-packages/remarkdown
   

2. put sphinxcontrib_markdown.py to your environment

3. configure your sphinx project (conf.py)

   Add following settings to conf.py:

   sys.path.insert(0, '.')
   extensions.append('sphinxcontrib_markdown')
   source_suffix = '.md'
   

4. write index.md!

sphinxcontrib_markdown.py

from docutils.core import Publisher


class MarkdownPublisher(Publisher):
    def __init__(self, *args, **kwargs):
        Publisher.__init__(self, *args, **kwargs)

        # replace parser FORCELY
        from remarkdown.parser import MarkdownParser
        self.reader.parser = MarkdownParser()

    def publish(self):
        Publisher.publish(self)

        # set names and ids attribute to section node
        from docutils import nodes
        for section in self.document.traverse(nodes.section):
            titlenode = section[0]
            name = nodes.fully_normalize_name(titlenode.astext())
            section['names'].append(name)
            self.document.note_implicit_target(section, section)


def setup(_):
    # replace Publisher
    import sphinx.environment
    sphinx.environment.Publisher = MarkdownPublisher

This is great. remarkdown seems to be breaking on raw HTML snippets though. But it's a great start! :)