Sphinx Markdown Extension
An Sphinx extension supporting for
sphinx.ext.autodoc with modules containing docstrings in Markdown.
How it works
This extension reads your docstrings in
Markdown, and translates it to
pandoc, so that Sphinx can deal with it. This only processes docstrings and it doesn't do anything to any other files which Sphinx reads. So, for example, if you have an
index.rst, that file still needs to be written in reStructuredText.
How to use it
Sphinx 1.4.5 or upper
Python 3.4 or 3.5 since
pypandoconly supports Python 2.7, 3.4 and 3.5.
pypandoc (install it by
pip install pypandocin
The default input format is GitHub-Flavored Markdown and you can change it to other format as long as Pandoc can support. For this, you need to change the
markdown_github to the format you want in the extension source file
Put this extension
mkdsupport.py into the directory containing
conf.py file which is also the root of your Sphinx project. Add the following code to
conf.py file to set module search path
sys.path of Python so that Sphinx can find the extension.
import sys import os sys.path.append(0, os.path.abspath('.'))
conf.py file so that this extension is enabled as following. And you can disable it by remove it from the extension list.
extensions = ['mkdsupport']
Actually you can put this extension to directory you want and put this directory to the
sys.path. However, the Sphinx project directory is suggested since the extension is not official. In this way, there is no pollution on Sphinx installation directory and it is easier for managing the settings.
If you change the input format, such as the default one
markdown_github, in this extension and there are no changes in your project source files, this extension will not be triggered and there will be no updates in your generated documentation.