Including parts of README.rst in your sphinx docs

readme_content_in_sphinx.rst

Taken from a post by Stuart Colville at https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/. Here only to make this star-able by myself.

In your README.rst add a marker marking from which point you want to start importing content:

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 in any rst file that is part of your sphinx documentation you can include the above content using:

.. include:: ../../README.rst
  :start-after: inclusion-marker-do-not-remove

Where the ../../README.rst path assumes the file you wish to include your README contents in is at your_package/docs/source. Adapt it accordingly if this is not the case.

I made a script to process the rst includes to import those includes and assemble the result into a monolythic RST File that can be rendered on Github.

Even nested includes are possible (call the build script multiple times), and all the include options like start-after, end-before, etc ...

So You can include code snippets, requirements, or other *.rst or txt Files and test the documentation build even on travis.

The script is shell friendly, supports piping and offers additional some string replacement function. It also has a very good error reporting (for instance when some :start-after: marker is not found, etc ...) showing You exactly on which line-number in which file the error occured.

I use it myself to include tested code snippets into the documentation, and build the documentation on travis automatically, before deploying to PyPi

Check it out, it might be useful !

https://github.com/bitranox...

Yours sincerely

Robert / Vienna