[Cython] "Cython's Users Guide"

Robert Bradshaw robertwb at math.washington.edu
Tue Apr 12 15:42:39 CEST 2011


On Mon, Apr 11, 2011 at 2:35 PM, Francesc Alted <faltet at pytables.org> wrote:
> 2011/4/11 William Stein <wstein at gmail.com>
>>
>> Hi,
>>
>> I'm teaching Cython in my Sage course yet again, and noticed that
>> again there are some very confusing aspects of the Cython
>> documentation organization, which could probably be improved by a few
>> simple changes.
>>
>>  1. At http://cython.org/ there is a big link in the middle of the
>> page labeled "Cython Users Guide" which goes to
>> http://docs.cython.org/.   However, http://docs.cython.org/ is *not*
>> the users guide -- it is "Cython’s Documentation".     In fact, the
>> Users Guide is Chapter 3 of the documentation.
>>
>>  2. Looking at http://docs.cython.org, we see that Chapter 2 is
>> "Tutorials".  But then looking down to Chapter 3 we see that it is
>> "Cython Users Guide".  Of course, that's what one is after having just
>> clicked a link called "Cython Users Guide".  So we click on "Cython
>> Users Guide" again.
>>
>>  3. We arrive at a page that again has "Tutorial" as Chapter 2.   For
>> some reason this makes me feel even more confused.
>>
>> Recommend changes:
>>
>>  1. Change the link on the main page from "Cython Users Guide" to
>> "Documentation"  or put a direct link into the Users Guide, or have
>> two links.
>>
>>  2. At http://docs.cython.org/ rename the "Cython Users Guide" to
>> "Users Guide", since it is obviously the Cython Users Guide at this
>> point and "Cython documentation" is in the upper left of the page
>> everywhere.
>>
>>  3. Possibly rename the tutorial in chapter 2 of the users guide to
>> something like "First Steps" or "Basic Tutorial" or something.

Thanks for the suggestions. Done.

> Yeah, that's something that we discussed in the past workshop in Munich
> (BTW, many thanks for providing the means for making this happen!).  The
> basic idea is to completely remove the Chapter 3 (Cython Users Guide) by
> moving its parts to either Chapter 2 (Tutorials), or either to Chapter 4
> (Reference Guide).  During the meeting we agreed that the doc repository
> should be moved (and has been moved indeed) into the source repo, so that
> modifications that affect to code and docs can be put in the same
> commit/branch. Also, the wiki has a lot of information that can be better
> consolidated and integrated into the User's Guide.
> In fact, I already started some job in this direction and created a couple
> of pull requests during the workshop (that they have been already
> integrated).  I plan to continue this job, but unfortunately I'm pretty busy
> lately, so I don't think I can progress a lot in the next weeks, so if
> anybody is interested in joining the effort for improving Cython's
> documentation, she will be very welcome indeed!

+1, and thanks, Fransesc, for the work you've started in moving us in
this direction.

- Robert


More information about the cython-devel mailing list