python-sphinxread-the-docstoctree

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


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


Solution

  • 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