Skip to content

Instantly share code, notes, and snippets.

@tk0miya
Created December 19, 2012 14:11
Show Gist options
  • Save tk0miya/4336929 to your computer and use it in GitHub Desktop.
Save tk0miya/4336929 to your computer and use it in GitHub Desktop.
sphinxcontrib_markdown
sys.path += ["."]
extensions += ["markdown"]
markdown_title = 'hello world'
source_suffix = '.md'
# -*- coding: utf-8 -*-
"""
sphinxcontrib_markdown
~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2012 by Takeshi Komiya.
:license: BSDL.
"""
import os
from tempfile import mkstemp
class MarkdownProcessor(object):
def on_builder_inited(self, app):
orig_find_files = app.env.find_files
def find_files(config):
orig_find_files(config)
app.env.found_docs.add('index')
app.env.find_files = find_files
def on_env_purge_doc(self, app, env, docname):
env.find_files = None
del env.find_files
if docname == "index":
docpath = env.doc2path(docname)
self._create_index(app, docpath, app.env.found_docs)
def on_source_read(self, app, docname, source):
if docname == 'index':
return
try:
input = mkstemp()
output = mkstemp()
os.close(input[0])
os.close(output[0])
with open(input[1], 'wt') as f:
f.write(source[0].encode('utf-8'))
cmdline = "pandoc -r markdown -w rst %s -o %s" % (input[1], output[1])
os.system(cmdline)
source[0] = open(output[1]).read().decode('utf-8')
finally:
os.unlink(input[1])
os.unlink(output[1])
def _create_index(self, app, filename, docs):
title = app.env.config.markdown_title or 'Untitled'
with open(filename, 'wt') as f:
f.write("%s\n" % title)
f.write("%s\n" % ("=" * len(title) * 2))
f.write(".. toctree::\n")
f.write("\n")
for file in sorted(docs):
if file != "index":
f.write(" %s\n" % file)
def setup(self, app):
app.add_config_value('markdown_title', None, 'html')
app.connect('builder-inited', self.on_builder_inited)
app.connect('env-purge-doc', self.on_env_purge_doc)
app.connect('source-read', self.on_source_read)
def setup(app):
md = MarkdownProcessor()
md.setup(app)
@MaxLazar
Copy link

MaxLazar commented Jan 3, 2013

Hello, thanks for sharing this!
I saved it in /Sphinx-1.1.3-py2.7.egg/sphinx/ext/ but still have error
WARNING: extension 'markdown' has no setup() function; is it really a Sphinx extension module?

Any advice how to install it?

Thanks!

@shimizukawa
Copy link

there are several ways to use this.

I recommend that save 'sphinxcontrib_markdown.py' as 'markdown.py' into the document root directory that have 'conf.py'. and set extensions=['markdown'] and set sys.path.insert(0, '.') in conf.py.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment