0

I'm trying to use Sphinx to auto-generate API documentation for a Python library, and I can't make it properly format the example code snippets in the docstrings - they do get indented but lines of the same indentation get concatenated (https://weka-io.github.io/easypy)

I understand that the problem is that the format I'm using to mark the code blocks is Markdown (indent them by 4 spaces) but Sphinx is expecting reStructuredText (code-block::)

I've tried googling for a solution and it recommended using recommonmark - but it seems to be for using .md files as the source. I'm using sphinx-apidoc to generate the "source" .rst files from the Python code - so it's not going to work (unless there is a way to make sphinx-apidoc generate .md files instead)

So - how do I make Sphinx treat just the Python docstrings as Markdown, leaving the elaborate reStructuredText framework as is for everything else?

Idan Arye
  • 12,402
  • 5
  • 49
  • 68
  • It looks like you just need to add a colon to introduce a literal block (`Example::` instead of `Example:`). See http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks (I don't understand what Markdown has to do with this). – mzjn Apr 17 '18 at 05:08
  • @mzjn Adding that extra colon is the reStructuredText syntax for code block, and just indenting by four columns is the Markdown syntax. This project has been around for a few years before I added the documentation generation, and if possible I prefer to change some Sphinkx configuration to make it accept markdown over modifying all the docstrings in the project to reStructuredText. – Idan Arye Apr 17 '18 at 08:52
  • OK... I'll just refactor everything to use reStructuredText... – Idan Arye Apr 17 '18 at 11:56
  • 4
    Possible duplicate of [Force sphinx to interpret markdown in python docstrings instead of restructured text](https://stackoverflow.com/questions/56062402/force-sphinx-to-interpret-markdown-in-python-docstrings-instead-of-restructured) – Florentin Hennecker Jun 06 '19 at 18:07

0 Answers0