Some 80% of my code is generated by higher order functions or is declared as a lambda expression. Typically, this results in fewer total lines of code and good code reuse. The problem I am having is that these types of functions are not processed properly by the automatic documentation generator Sphinx.
This blog has a partial solution : directly assign values to __doc__ and __name__. This is, however, neither necessary nor sufficient to get the functionality we desire with Sphinx. You can document functions generated with higher order functions or lambda expressions like module variable by following them with a triple-quote string.
foo = lambda x:x
"""Identity function"""Produces something like the following in the automatically generated documentation :
foo
Identity function
This is better, but not quite enough. We don't get the argument list, the some of the formatting is a bit odd. I'll let you know if I figure something out. At the moment I can't even figure out how to infer the argument list of a lambda function.
Update : the answer may have something to do with this :
It’s possible to override the signature for explicitly documented callable
objects (functions, methods, classes) with the regular syntax that will
override the signature gained from introspection:
.. autoclass:: Noodle(type)
.. automethod:: eat(persona)
This is useful if the signature from the method is hidden by a decorator.
New in version 0.4.
No comments:
Post a Comment