Previously the example-based documentation was in the README.rst file in the same folder alongside the code and other supporting files. This documentation looked good on Github but due to the way the documentation was compiled, when simply "include"-ing this file in the ReadTheDocs .rst page, all the links to the images broke (relative path was incorrect when referenced from RTD). The best fix I could come up with was moving all the documentation content to the RTD page and providing a web URL on the README. That URL always points to the latest released version which is probably the right thing to do.
This works well with the web site in one window and another window running the example. The document, images, tables does not clutter the running files.
Previously the example-based documentation was in the README.rst file in the same folder alongside the code and other supporting files. This documentation looked good on Github but due to the way the documentation was compiled, when simply "include"-ing this file in the ReadTheDocs .rst page, all the links to the images broke (relative path was incorrect when referenced from RTD). The best fix I could come up with was moving all the documentation content to the RTD page and providing a web URL on the README. That URL always points to the latest released version which is probably the right thing to do.