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.
>
Wonderful!
> So what I ask in return are answers to questions I will have 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. 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.
>
> 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.
>
> 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.
>
Make sure to read both paper preprints posted, that's a start. I'll be
glad to tell you everything you need afterwards.
> 3) What Is currently on the functionality-implementation agenda. What
> is Cython's road map for say, the next six months.
>
trac.cython.org mostly contains this. But: This is a bit hard, as
development of new features usually happens because a developer suddenly
gets a kick out of an idea; it's not something that's planned. That's
hard to change as long as Cython development is entirely spare time
hobby work.
Perhaps we should start having higher-level tickets to give an easier
overview for folks though. Like "Full Python compatability" as one
meta-ticket etc.
> 4) Come to think of it.. I think it would be cool to highlight
> Cython's "Google Summer of Code" participants and their contributions.
>
> 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.
>
1) Like Robert says, a good place to start is docs.cython.org and its hg
repository. Just familiarise yourself with how to use Sphinx (if you
want to use it) and perhaps create a wiki page documenting how to work
with the docs.
2) Let's use Trac for this effort! I already created Documentation
milestones and category, there's a few tickets there already (like
integrating the posted preprints into the docs). If you tell us your
trac account (get one if you haven't) we'll give you rights to close
tickets etc.
http://trac.cython.org/cython_trac/report/3
3) I'm wondering if we should split up "docs.cython.org" into subsections:
- Cython Tutorial (based on the paper, then updated in the future)
- Cython Reference Manual (based on current docs, but with some things
stripped out)
- Numerical computations in Cython (a copy of the corresponding paper)
See docs.scipy.org for an example of how multiple documentation sources
are presented.
4) I think the current Cython/NumPy tutorial should be removed in favour
of the above generic tutorial + numerical Cython paper; opinions on that?
Thanks again!, this effort will definitely keep me motivated to keep
improving Cython!
Dag Sverre
_______________________________________________
Cython-dev mailing list
[email protected]
http://codespeak.net/mailman/listinfo/cython-dev
