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

6
votes

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

1
python-3.xpython-sphinxsectionstoctreecommonmark

1 Answers

6
votes

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
========