We've had a number of typos and other errors reported against this project's documentation, and one idea I had was to run pytest against all of the code samples in the docstrings. In order to do this, I needed to:
Implement a FakeAirtable context manager class, which is capable of simulating basic interactions by mocking methods on other classes (like Table and SerializableModel).
Implement a custom output checker for doctest that can support the JSON-style indentation we use in our examples, which is more legible (imho) but is not how repr() output appears.
Populate the fake Airtable object with some record data that matches the expectations of our docstrings, as well as rework quite a few examples.
Limitations/issues with this approach:
It will be more work to add examples to our documentation, which might discourage patches.
It will be very challenging to document scenarios that assume interactions with the Airtable UI in between lines of code being executed. I'm not sure we have any of those today.
FakeAirtable cannot be nested because it uses autospec, which means it can't document its own use. I haven't figured out a clean way around this yet.
The branch has a few examples of the changes required to some of the library's modules in order to make them pass tests. I'm opening this as a WIP to solicit input on whether it's worth continuing down this route, or if I should just grab FakeAirtable (which is useful in other contexts) and ditch the rest.
We've had a number of typos and other errors reported against this project's documentation, and one idea I had was to run pytest against all of the code samples in the docstrings. In order to do this, I needed to:
FakeAirtable
context manager class, which is capable of simulating basic interactions by mocking methods on other classes (likeTable
andSerializableModel
).doctest
that can support the JSON-style indentation we use in our examples, which is more legible (imho) but is not howrepr()
output appears.Limitations/issues with this approach:
autospec
, which means it can't document its own use. I haven't figured out a clean way around this yet.The branch has a few examples of the changes required to some of the library's modules in order to make them pass tests. I'm opening this as a WIP to solicit input on whether it's worth continuing down this route, or if I should just grab
FakeAirtable
(which is useful in other contexts) and ditch the rest.