In snakeoil, a core rule of our codebase is that extensions must be optional- this is primarily done to make the initial steps of porting pkgcore to a platform easier, and to enable some usages that aren’t extension friendly.
One problem I’ve ran into however is how best to keep your extension docstrings in sync with the native implementations docstrings. I’m not a fan of relying on developers to update docstrings in two places, and I’m not a fan of just storing the documentation on a website or something similar (I generally like my pydoc invocations to be useful, rather than stubs telling me to load a webpage- personal preference however).
Anyone got any suggestions? One thought I’d had was to split the docstrings out into a module the native and extension implementations could import, but that seems a bit too much like a kludge to me- plus it complicates the code a fair bit. The other thought I’d had was to add a set of tests checking extensions vs native, to ensure the two are in sync, but that doesn’t solve the core problem- just make it easier to do the dual maintainence.
So how are others solving this?
