Can't display multiple .md files in .rst toctree Sphinx

Question

I can render my Readme.md files in Sphinx using recommonmark. But when I try to put in multiple Readme files in a .rst file toctree only the first one can be accessed from the documentation link.

Kick! KVM
=========

Source Code: https://bitbucket-eng-rtp1.cisco.com/bitbucket/projects/KICK/repos/kickdb/browse/kick/kvm


ReadMe
------
.. toctree::
    :maxdepth: 2

    ./README.md

Tests ReadMe
------------
.. toctree::
    :maxdepth: 2

    ./tests/README.md


KVM Module Code
---------------

.. automodule:: kick.kvm.actions
    :members:
    :undoc-members:

I can see the both the Readme files in the folder structure, but the links don't work when trying to access them from the rendered html page.

Here is an image for the folder structure.

Any help appreciated, Thanks!

Here is the error that pops up in the Sphinx build -

/workspace/kick_device2/kick/kvm/kvm.rst:16: WARNING: toctree contains reference to document 'kick/kvm/tests/README' that doesn't have a title: no link will be generated

Gerladina

Answer 1

The warning indicates you need to add a title to the file tests/README.md. Sphinx considers the h1 level to be the title of a page. From the markdown syntax documentation:

# My Title

or

My Title
========

Baseler

Thanks for the info! That solves the problem, but the files are autogenerated. Is there a way to fix the issue directly from the .rst ? – Gerladina

No. You would have to either go upstream of the autogeneration tool to configure headings in the source or post-process the autogenerated .md file to include such markup. – Baseler