Skip to content
An Sphinx extension supporting for sphinx.ext.autodoc with modules containing docstrings in Markdown
Python
Branch: master
Clone or download
Pull request Compare This branch is 16 commits ahead of embolalia:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
README.md
mkdsupport.py

README.md


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 reStructuredText using 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

Requirements

  • Sphinx 1.4.5 or upper

  • Python 3.4 or 3.5 since pypandoc only supports Python 2.7, 3.4 and 3.5.

  • pypandoc (install it by pip install pypandoc in cmd)

Usage

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 mkdsupport_use_parser from markdown_github to the format you want in the extension source file mkdsupport.py.

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('.'))

Add mkdsupport to 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']

Reminders

  • 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.

References for Developers

You can’t perform that action at this time.