I've almost finished the transform in charge of embeding functions signatures in docstrings. I want to ask your about some issues I need to handle to finish it.
* Position in the transform pipeline: I'm curently inserting the auto-signature transform after the 'ResolveOptions' one in the transform pipeline. Dag, tell me if this is OK. * Enabling option?: Should I used a pragma-like option (like 'boundscheck') or a global option (like '--embed-positions')?. I do not really see the benefit of selectively enabling the embeding of signatures, so I believe we should use a global option. * Always embed?: If a function do not have a docstring (ie., node.doc is None), should I embed the signature anyway? Perhaps this could be controlled with the '--embed-signatures' options providing a level, like let say the '--cleanup' option? * Remove identation?: What do you thing about previously call 'textwrap.dedent()' on the original function docstring if it is present? Do you believe there ar use cases for preserving the common level of identation in docstrings? If docstrings are not 'dedented' (Do such word exists?), then we are going to be carefull about the other option '--embed-positions', that do not take into account docstring identation. * Signature format: I'm currently generating a dotted name 'ClassName.methodname' for the signature. Not completelly sure If I should add the 'ClassName', or a full namespace name 'ModuleName.ClassName.NestedClassName', or just the undotted 'methodname'. About argument list, 'self' is there, and types are there; no 'return_type' is yet generated, not sure how to build a meanigful value. In short: appart from the ClassName being added, the signature looks almost the same that the function definition in Cython source code (though I'm not currently generating the 'not None' stuff. it looks really ugly!!) Finally, builtin help() and IPython seems to work just fine with the currently generated signatures. Epydoc needs a custom script with a few lines monkeypatching the regex used for parsing builting functions signatures. I've not tried Sphinx yet, not even sure if it handle builtin functions like Epydoc has. All my current implementation lives in two scripts: one monkeypatching Cython, and other for Epydoc. If any of you want to give a try before pushing this in cython-devel, just let me know, I'll send the scripts. Regards, -- Lisandro Dalcín --------------- Centro Internacional de Métodos Computacionales en Ingeniería (CIMEC) Instituto de Desarrollo Tecnológico para la Industria Química (INTEC) Consejo Nacional de Investigaciones Científicas y Técnicas (CONICET) PTLC - Güemes 3450, (3000) Santa Fe, Argentina Tel/Fax: +54-(0)342-451.1594 _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
