General questions

[evildmp]

• [ ] We include the autogenerated CHANGELOG.rst file. This uses different heading levels form the rest of the documentation, and as a result, every single release is listed in the contents under "about" on the index page. Can these levels be changed? === would need to become ---, and --- would need to become ^^^.
• [ ] Heading capitalisation styles are inconsistent (The writing and reporting of assertions in tests vs Good Integration Practices - the former is easier to read)
• [ ] The Makefile and conf.py need some attention. I'd like to discuss them with someone!
• [ ] Lots of errors like: /Users/daniele/pytest/doc/en/env/lib/python2.7/site-packages/Babel-2.4.0.dist-info/DESCRIPTION.r st: WARNING: document isn't included in any toctree - not sure where these are coming from.
• [ ] The entire Examples section needs to be removed, and its contents worked into other sections where they can be properly supported with some context.
• [ ] What is doc/en/genapi.py and why is it needed?
• [ ] The entire test directory (along with funcargs.rst) looks like it should be simply deleted.
• [ ] The entire proposals directory looks like it should be simply deleted.

[flub]

A few random thoughts on your questions

• If we want to keep proposals it could probably go under contributing somehow
• genapi seems not used, probably a relic from the past so i guess deleting is fine

[nicoddemus]

Can these levels be changed? === would need to become ---, and --- would need to become ^^^.

Definitely, we can change it. We would need to manually update past entries, but future entries can be changed in the changelog/_template.rst file.

Heading capitalisation styles are inconsistent

Lots of errors like: /Users/daniele/pytest/doc/en/env/lib/python2.7/site-packages/Babel-2.4.0.dist-info/DESCRIPTION.r st: WARNING: document isn't included in any toctree - not sure where these are coming from.

I suggest to use tox to generate the docs locally. Just install tox in a virtualenv and run:

$ tox -e docs

This will generate the docs in doc/en/_build.

The entire Examples section needs to be removed, and its contents worked into other sections where they can be properly supported with some context.

Agreed, most examples would fall under the "How-to" sessions I believe, while some of them would have to be split inito "How-to" and "Reference".