Run doctests on all examples in sphinx documentation
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Microfiber |
Fix Released
|
High
|
Jason Gerard DeRose |
Bug Description
Documentation that doesn't get automatically tested is worthless! You can quote me on that :P
Last month I was still stumbling around figuring out how to write documentation using Sphinx, so I didn't get things setup to automatically run doctests for all the examples in the documentation. Plus I was a bit confused as to whether this was possible for Python3 modules... but after looking into things a bit more, it seems that although you can't use the `autodoc` extension for Python3 modules, you can use `doctest`.
Anyway, these docs tests will be a bit tricky as by its nature CouchDB involves a lot of random values (at the very least doc['_rev'] has a random value after the '1-', '2-', etc). So our options are:
1) Setup the doctests to use a dummy HTTP connection that will return consistent, canned values
2) Setup the doctests to create temporary CouchDB instances using `usercouch` and make liberal use of doctest: +ELLIPSIS
I'm leaning toward (2) personally as then we make sure the examples truly work with a real-live CouchDB.
In a related bug, we're going to start running all the live tests by default and set them up using `usercouch`:
Related branches
- David Jordan: Approve
-
Diff: 1423 lines (+828/-380)4 files modified.bzrignore (+1/-1)
doc/couchdb_api.rst (+679/-287)
doc/microfiber.rst (+133/-92)
setup.py (+15/-0)
Changed in microfiber: | |
milestone: | 11.10 → 11.11 |
Changed in microfiber: | |
milestone: | 11.11 → 11.12 |
Changed in microfiber: | |
milestone: | 11.12 → 12.01 |
Changed in microfiber: | |
milestone: | 12.01 → 12.02 |
Changed in microfiber: | |
milestone: | 12.02 → 12.03 |
Changed in microfiber: | |
milestone: | 12.03 → 12.04 |
Changed in microfiber: | |
milestone: | 12.04 → 12.05 |
Changed in microfiber: | |
milestone: | 12.05 → 12.06 |
Changed in microfiber: | |
milestone: | 12.06 → 12.07 |
Changed in microfiber: | |
milestone: | 12.07 → 12.08 |
Changed in microfiber: | |
milestone: | 12.08 → 12.09 |
Changed in microfiber: | |
milestone: | 12.09 → 12.10 |
Changed in microfiber: | |
milestone: | 12.10 → 12.11 |
Changed in microfiber: | |
milestone: | 12.11 → 12.12 |
Changed in microfiber: | |
milestone: | 12.12 → 13.01 |
Changed in microfiber: | |
milestone: | 13.01 → 13.02 |
Changed in microfiber: | |
milestone: | 13.02 → 13.03 |
Changed in microfiber: | |
milestone: | 13.03 → 13.04 |
Changed in microfiber: | |
milestone: | 13.04 → 13.05 |
Changed in microfiber: | |
milestone: | 13.05 → 13.06 |
Changed in microfiber: | |
milestone: | 13.06 → 13.07 |
Changed in microfiber: | |
milestone: | 13.07 → 13.08 |
Changed in microfiber: | |
milestone: | 13.08 → 13.09 |
Changed in microfiber: | |
milestone: | 13.09 → 13.11 |
Changed in microfiber: | |
milestone: | 13.11 → 13.12 |
Changed in microfiber: | |
milestone: | 13.12 → 14.01 |
Changed in microfiber: | |
milestone: | 14.01 → 14.02 |
Changed in microfiber: | |
assignee: | nobody → Jason Gerard DeRose (jderose) |
status: | Triaged → In Progress |
Changed in microfiber: | |
status: | In Progress → Fix Committed |
Changed in microfiber: | |
status: | Fix Committed → Fix Released |
Ah, forgot link to Sphinx documentation for doctest extension:
http:// sphinx. pocoo.org/ ext/doctest. html