CenterForOpenScience/pydocx — pull request #36 by kylegibson (2014-04-18 22:27:34+00:00)
Title: Create project homepage, changelog and standardize sphinx/rst/md docs

I finally settled on a documentation plan I like for mixpanel-celery, which I recommend. Add a separate file for the [pypi description](https://github.com/winhamwr/mixpanel-celery/blob/master/pypi_description.rst).

I kind of like this paradigm:

1. A `README.md` file so that you can use github's built-in page generation for a slick, easy-maintenance, one-page [project home page](http://weswinham.com/mixpanel-celery/). Just go to Settings, then under **GitHub Pages** click *Automatic Page generator*. Then tell it to update based on your readme, pick a theme and publish.
2. Comprehensive Sphinx documentation hosted and auto-generated on readthedocs
3. A `pypi_description.rst` file that just summarizes the project, links to the project website and links to the documentation.
4. A `CHANGELOG.rst` file that you update as you merge pull requests. Ideally, this would be pulled in after the `pypi_description.rst` to create the pypi page in your `setup.py`, but I haven't done that yet.