This will probably be of use to about 3 people, and I'm one of them. If you feel your eyes glazing over, don't fret and look at this kitten picture instead:
The problem
I wanted to add some content to both our docs (built via sphinx docs and written in ReStructuredText) and our README.rst on github.
Because duplication is always best avoided I wanted to make the documentation once and have it published in both places. This way if changes are needed there's only one thing to update.
ReStructured text has a handy include directive which allows you to include content files by path references.
I tried using that in the README.rst and our docs. Unfortunately on github this fails for the README because github don't allow the include directive for security reasons.
The solution
The answer (after some experimentation) was to put add the text directly to the README.rst and then include it from the docs.
There's a neat facility in RST that allows you to specify text to start from when using the include directive. This means you don't have to include an entire file - for example in my case I didn't want the whole README to be added to the docs.
After some experimentation this is what I ended up with:
This is an approximation of the README.rst:
Blah blah project
=================
Here's all the actual readme content.
.. inclusion-marker-do-not-remove
My Awesome content I wish to include
------------------------------------
Blah blah etc etc.
And then I created a readme_include.rst that looked like this:
.. include:: ../../README.rst
:start-after: inclusion-marker-do-not-remove
With that in place I added the readme_include to the TOC in the main docs and problem solved.
This trick works via the start-after directive which includes only the text after the string.
Using a comment to provide a marker means you can include everything after that marker.
Here's the docs for the include directive. There's a few other options that allow you to limit what content is included.