[Cython] Documentation

[Robert Bradshaw]

On Sep 27, 2008, at 8:27 AM, Dag Sverre Seljebotn wrote:

> Gabriel Gellner wrote:
>> Well seeing the need I am writing up a tutorial for simple  
>> compilation and
>> usage for my Sphinx docs. This leads me to update some of the  
>> other pages
>> to
>> reflect recent changes, and I would like some feedback to ensure I
>> understand
>> everything!
>
> Note that I wrote some paragraphs on simple compilation etc. in my  
> NumPy
> tutorial (wiki.cython.org/tutorials/numpy).
>
> Question: Can I as a Cython developer modify these docs?

The repository is up at http://hg.cython.org/cython-docs/ , so you  
can make changes, submit patches/bundles, etc. If Gabriel is willing,  
I could give you push access.

> For instance, take the compilerdirectives docs currently at
>
> http://wiki.cython.org/enhancements/compilerdirectives
>
> where should I have added this? Similar for documenting the  
> behaviour at
> http://wiki.cython.org/enhancements/buffer.
>
> Ideally I'd like either a) a "docs" subdirectory in the Cython  
> repository,

That does make sense. We do have a Doc subdirectory already, but it's  
not near as up to date (or as nice looking).

> or b) a wiki-like interface to the official docs. (Is there a Sphinx
> plugin to MoinMoin perhaps?)

The "all documentation is on the wiki" approach hasn't (yet) yielded  
the most helpful docs so far, which is why I'm so enthusiastic about  
this project. Both certainly have their place, but having a (more)  
stable set of refined docs is very valuable. The process of migrating  
information from the wiki into the docs themselves (as in this  
thread) is a useful one to get something polished and accurate.

> a) has the advantage that it is simple and means that documentation is
> versioned together with the sources which has many advantages (easy to
> check whether the "with" statement was supported in version X). A  
> single
> commit that adds a feature would then change the docs as well.

[...]

> BTW, great that you are doing this, documentation has a way of falling
> behind...

Unless someone keeps it up :). Most of the basic stuff isn't changing  
though, and that's often the hardest stuff for new users.

- Robert