7

I am documenting a Python 3 project with Sphinx. The Sphinx docs are in doc, and I would like to include the contents of my top level README.md in my index. Assume that I can get Sphinx to parse and render Markdown using the instructions in issue #825.

If my doc/index.rst looks like this:

Index
=====

Modules
-------

.. toctree::
   :maxdepth: 2

.. include:: ../README.md

...the markdown is parsed as reStructuredText (because that's how the include directive works). This means that most of the markdown formatting is ignored.

Even a link won't work: it's not possible to directly create a link to a document above doc/, and any workaround still requires including a markdown document within reST. In any case, what I really want is the content rendered in the index.

Is it possible to somehow tell Sphinx that one part of a document is in a different markup language than the rest, or to change parsing contexts for a section of a document? Or is there some other way to tell it to inject one document into another after the parsing has been done?

Community
  • 1
  • 1
detly
  • 29,332
  • 18
  • 93
  • 152
  • 1
    Not really an answer to your question, but couldn't you write the README in reST? Although markdown is more common, it's not unusual to see it in reST too, Github and the like will parse it with no problem. – gozzilli May 23 '16 at 06:41
  • @gozzilli That'll be the solution if I can't use markdown, but my first choice for longish prose is markdown. – detly May 23 '16 at 06:57
  • I'm pretty certain this is not going to work. You can't get an include and Markdown parsing at the same time, only one or the other. However, as you are docummenting a Python project, your README should be in ReST anyway so that you can pull it into your setup.py file as the `long_description`. PyPI requires the `long_description` to be in ReST, so it is a rare situation in which the README of a Python project is in Markdown. – Waylan May 23 '16 at 13:36
  • @Waylan I've never deployed to PyPI, so I hadn't come across this before. It's probably a bit too long for a package manager long description anyway. But if it's not possible, that's fine. Really I'd rather Github let me do includes from README rather than the other way around. – detly May 23 '16 at 21:32
  • You may not use PyPI, but most Python packages do which means that most Python package READMEs are in ReST and most people have not encountered your situation. As you are facing a rare, uncommon problem, it is less likley that anyone has developed a solution. At least you now know why. – Waylan May 24 '16 at 03:08

0 Answers0