use the same README content in sphinx and github - relative links

Question

I'm adding a Read The Docs page for my project. For now, I want the same content on my Read The Docs homepage as in my README. My docs/index.rst file looks like:

.. include:: ../README.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

This mostly works, except for relative links. For example, my README contains:

See `INSTALL.rst`_ for advanced and detailed instructions.

Since Sphinx builds everything within the docs directory, it is expecting to find INSTALL.rst inside the docs directory.

Since Github renders the file from root, it expects to find INSTALL.rst in the root directory.

How can I make Github and Read The Docs (Sphinx) both render relative links correctly without having duplicate files (or preferably, any duplication)?

Answer 1

Try using the symboric link.

In the sphinx directory:

INSTALL.rst -> ../INSTALL.rst