2

As M2R is deprecated in Sphinx3. I tried to use recommonmark in order to include README.md to my documentation.

I have the following structure

project
|--README.md
|--docs
|--|--conf.py
|--|--index.rst
|--|--...

In conf.py I added recommonmark to extensions. and have '.md' in the source_suffix

In the index.rst

I have

.. toctree::
   :maxdepth: 2


   ../README.md
   modules

But Sphinx couldn't find it:

WARNING: toctree contains reference to nonexisting document 'README'

I can solve it by creating a softlink of README to the docs folder. But this doesn't seem quite right for version control. As I worries the build will break on other machines, or in future changes of configuration.

So is there a way to include README.md from the project directory to index.rst?

Many thanks

bad_coder
  • 11,289
  • 20
  • 44
  • 72
J_yang
  • 2,672
  • 8
  • 32
  • 61
  • Notice that recommonmark is deprecated in favor of myst-parser https://github.com/readthedocs/recommonmark/issues/221 – astrojuanlu May 06 '21 at 19:40

1 Answers1

0

You can use an indirection.

index.rst

.. toctree::
    
    readme

readme.rst

.. include:: ../README.md

Pyramid docs do this.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 1
    Unfortunately that doesn't work either. It complain read.rst has no title. It i added a title. README.md is directly loaded as rst, which messed up all the formatting. In Pyramid it doesn't have the issue because all files are rst... Before with m2r, I can use mdinclude:: instead of include::, but now it is no longer supported. – J_yang Jul 04 '20 at 13:22
  • The indirection works, otherwise you would not get a new error regarding the syntax of your README.md. Please edit your question with the source of your README.md so I can help further. Another option is to run a script that converts your README.md to valid reST when you build docs and put it in your docs directory. – Steve Piercy Jul 05 '20 at 08:56
  • I have the same issue. Any solution so far? – pjk Nov 19 '20 at 10:42