Couldn't add relative path of README.md to Sphinx using recommonmark

user_4930109 0
Viewed 544

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

python-sphinx python
1 Answers

You can use an indirection.

index.rst

.. toctree::
    
    readme

readme.rst

.. include:: ../README.md

Pyramid docs do this.

user_22149330
Related