On Sep 30, 2009, at 1:41 AM, Peter Alexander wrote: > Hi all. > > I'd like to make the proposition of devoting myself over the next few > days to updating the documentation for cython... completely.
Woohoo! > So what I ask in return are answers to questions I will have For sure, ask away. Being so deep in the project it's hard for me to see what's not obvious, but I'll be glad to answer any questions that come my way. > And for all of you to blurt out, in this thread, anything you can > possibly > think of that might be of interest to a "well oiled" set of > documentation. The most useful thing to push is how "easy" it is--with few exceptions you can just paste your .py code right into a .pyx file and compile. Then incrementally typing what needs to be typed (using cython -a and benchmarking). I think something that easily escapes people is that you don't need to (or want to) type everything, and you can type stuff incrementally as needed. A (set of) complete working examples is always good, maybe a running example like the integrate one. Easily downloadable and tweak-able, and we should make sure to get it into our regression tests. > I will put a lot of thought and detail into how it will > be perceived and digested by both the casual and technical users. > > If we also need to enhance tools like sphinx/pygments, etc., I'll be > glad to tackle that as well. About a year ago Gabriel Gellner put a lot of work into consolidating the thinly scattered documentation from all over and making http:// docs.cython.org/ The repo is at http://hg.cython.org/cython-docs/ . You could start from that or start from scratch, but it'd be nice to have a single uniform place to go for everything. There's also the two recent SciPy papers that were posted, we'd be happy to provide sources. > Right off the bat, off of the top of my head, I'd like to clarify > Cython's ability at this point... > > 1) We need to establish for users Cython's current state of > capability. Cython's "under the hood" ability to digest > meta-programming is an enigma to the uniformed user. For example, A > question I constantly ask my-self.. "Is that optimized to C code or am > I still dealing with the Python code". Do I need to use C-API calls or > not. Like for instance if I use the {} operator set.. is it still > endowed with python overhead, or is current cython magic able optimize > it. Yep, this would be really useful. Cython -a should not be underestimated to let a user answer this question themselves for any bit of code they care about, especially as it's constantly changing (e.g. nearly every version adds more direct C/API calls over Python ones). In nearly all cases, if you have to use a C/API call, that's an optimization just needs to be written into Cython itself. > 2) I'm a numbers guy. I really need to know exactly where we stand > with numpy and the buffer interface. Particularly, with structured > array's. Dag could comment more on this (and the tutorial he has expands a lot). In summary, indexing ndarray types are well supported and fast, and more is still under development/debate. > 3) What Is currently on the functionality-implementation agenda. What > is Cython's road map for say, the next six months. Good question. There isn't much of one, really, as we mostly implement new features and fix bugs on demand. However, that's not to say a roadmap isn't a good, and perhaps overdue, idea. I've created http://wiki.cython.org/roadmap and will try to put some thoughts there, though personally the next 6 months are going to be busy with mostly non-Cython stuff. There's also http://wiki.cython.org/enhancements/ , which is less time- focused. The 1.0 goal is to be able to compile 100% of Python 2.6 syntax, though optimizations and better numerical support are areas of development as well. > 4) Come to think of it.. I think it would be cool to highlight > Cython's "Google Summer of Code" participants and their contributions. Yep. Merging both projects definitely belongs on the roadmap. One thing that's currently poorly documented is how to wrap C++ code, which will become a lot easier once we merge Danilo's code, so I'm torn how much time to spend on this. > 5) etc.. etc.. > > So, lay it on me and I will do what it takes to make Cython's > documentation shine. I'm a big advocate of thoughtful documentation > you see.. considering OSS is entirely how I've learned what I do know > about computer science. I might peruse the mailing list looking for common questions/ misunderstandings. The wiki has a lot of good stuff too that should get moved/mirrored in a more stable and organized way. New features are often only discussed on the mailing list, if anywhere (e.g. embed/ freeze), let's change that! The global structure of the documentation could be looked at as well, e.g. special methods probably should be a subsection of extension types, and "Differences between Cython and Pyrex" probably isn't as important as "Differences between Cython and Python" and "Early Binding for Speed" should probably come earlier. Thanks again for looking at this! - Robert _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
