How to use the README.md file as homepage for shpinx readthedocs

Question

I have a README.md file which contains general overview of the package, and would like to add that file as main homepage to my documentation using spinx, can you please tell me how can I add it to my index.rst? thanks in advance

index.rst

my_apckage
==========

.. toctree::
   :maxdepth: 4

   my_package.main_page

PS: since I'm a beginner in Sphinx, I adpoted the example here for conf.py

Answer 1

You can use include directive for this like:

my_apckage
==========

.. toctree::
   :maxdepth: 4

   my_package.main_page

.. include:: ../README.rst

If you have README in Markdown (which I believe is the case) you can do the following. Also you will be needing an extension for parsing markdown. (I have used MyST)

.. include:: ../README.md
   :parser: myst_parser.sphinx_
   :start-after: <!-- index.rst content start -->

You can also configure how much to include a file For example you can see my index.rst file for this project. The index.html is 99% README.md