Phoenix doc patch

Hi,

Here a first try me fixing up (rst'ify) some of the doc strings, they are not finished, i.e. not spell checked etc.

Please be gentle with the critique:-) .

Some notes and questions mainly in relation to the lib.patch.
-- :note: or .. note:: etc
-- @param whatever: is this fine or only :param `whatever`:
-- code signature like this "IsEmpty(self) -> bool" should be removed, correct?

In lib.agw.InfoBar I often see :param etc terminated with ";" should this always be done, or ...?

Linking/cross-referencing:
Any guide lines when one should link?

E.g.:
:type `pos`: tuple or `wx.Point`

will wx.Point in this way be linked to the doc for wx.Point or do we need to do L{wx.Point} or should it be :class:`wx.Point` or ....?

Do we have have a readme on formatting etc we should use? Maybe just a link to things like:

Paragraph level markup see:
www.sphinx.pocoo.org/markup/para.html

Info field list (e.g. :param ....: ) see:
sphinx.pocoo.org/domains.html

Cross-reference Python objects see:
sphinx.pocoo.org/domains.html - I assume we can drop :py: i.e. just use :mod: instead of :py:mod:

Will keep on going with the wx.lib folder and 'rst'ify" existing documentation, should anyone else start working on this then we should setup of system to coordinate the effort so not to waste our time doing the same thing twice.

Werner

etg.patch (3.96 KB)

lib.patch (14.4 KB)

Hi Werner,

Hi,

Here a first try me fixing up (rst’ify) some of the doc strings, they are not finished, i.e. not spell checked etc.

Please be gentle with the critique:-) .

Some notes and questions mainly in relation to the lib.patch.

– :note: or … note:: etc

I always use … note::, but I can easily modify the SphinxGenerator to automatically convert all these :thing: to … thing::, as I do with the AGW docs.

@param whatever: is this fine or only :param whatever:

I am not sure Sphinx and docutils understand the @param syntax (but I may be mistaken). Again, if the patches become boring to make because of these changes, I’ll adapt the SphinxGenerator to convert the @stuff to :stuff.

– code signature like this “IsEmpty(self) → bool” should be removed, correct?

If the code is pure Python, I think so. Otherwise I believe you should leave it there as SphinxGenerator uses this information to retrieve the return type of a method.

In lib.agw.InfoBar I often see :param etc terminated with “;” should this always be done, or …?

No, I just do it out of habit, you can terminate a param docstring in the way you like (a full stop, nothing at all, etc…)

Linking/cross-referencing:

Any guide lines when one should link?

Uhm, I will think about this when I write a stub of the docstring guidelines, but in general I link to another method/class using the … seealso:: construct when I think it could be useful for a user to see other methods.

E.g.:

:type pos: tuple or wx.Point

will wx.Point in this way be linked to the doc for wx.Point or do we need to do L{wx.Point} or should it be :class:wx.Point or …?

I believe it should be either wx.Point or better :ref:Point or even better :class:Point (without the module extension).

Do we have have a readme on formatting etc we should use? Maybe just a link to things like:

Paragraph level markup see:

www.sphinx.pocoo.org/markup/para.html

Info field list (e.g. :param …: ) see:

sphinx.pocoo.org/domains.html

Cross-reference Python objects see:

sphinx.pocoo.org/domains.html - I assume we can drop :py: i.e. just use :mod: instead of :py:mod:

I will start a draft tomorrow about the docstrings “standards” as I will have a bit more time. I’ll let you know when I have uploaded it on SVN.

Will keep on going with the wx.lib folder and 'rst’ify" existing documentation, should anyone else start working on this then we should setup of system to coordinate the effort so not to waste our time doing the same thing twice.

Werner

To unsubscribe, send email to wxPython-dev+unsubscribe@googlegroups.com

or visit http://groups.google.com/group/wxPython-dev?hl=en

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”
http://xoomer.alice.it/infinity77/

···

On 30 March 2012 18:24, werner wrote: