I would advise putting .rst files in the docs/ folder and using Sphinx (http://sphinx-doc.org/) to make nicely structured and formatted docs. These docs can subsequently be published to readthedocs.org and updated on every push to Github. https://read-the-docs.readthedocs.org/en/latest/getting_started.html