Phoenix and pubsub documentation strings

[Werner]

Hi,

Any plans to adapt more Phoenix style doc strings?

Especially the module doc strings should be enhanced to make listings
like this nicer and more usefull.

http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.html#module-lib.pubsub.core

The initial page:

http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

would be nice to be updated and to include a sample or two on how to use
pubsub, or maybe even having some samples.

The doc standard used is explained here:
http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

I would be willing to help on this effort and could provide e.g. pull
requests or if you stay on SVN patches - but it would be nice if you
moved to git
(http://sourceforge.net/p/forge/documentation/Git/#management) when you
have a spare moment:-) .

Werner

[oliver]

Hi Werner, I appreciate the offer but again this seems like a big duplication of effort, the users should be referred to pubsub.sourceforge.net, is structured correctly (only exposes what typical/power user would need, but not the guts like core), examples and such  The core should not be documented for wxpython users. So all that work you are doing or wishing has already been done. Let's find another way to handle this. 

Oliver

Werner

--
You received this message because you are subscribed to the Google Groups "pypubsub" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pypubsub+unsubscribe@googlegroups.com.
To post to this group, send email to pypu...@googlegroups.com.
Visit this group at http://groups.google.com/group/pypubsub.
For more options, visit https://groups.google.com/groups/opt_out.

--

Oliver

Contributor to Open Source: PyPubSub, Lua-iCxx, iof

Contributor to StackOverflow

[oliver]

Forgot to mention, I will create a github repo for pubsub for wxpython. All project management for pubsub (bug tracking etc) will remain on SF.net but this will make it easy for me to release pubsub to wxpython (i'll just push latest SVN to github), and for wxpython developers to pull it when needed. 

P.s. the doc standards link is wrong, can you resend

[Werner]

Hi Oliver,

On 14/02/2014 07:05, oliver wrote:

Forgot to mention, I will create a github repo for pubsub for wxpython. All project management for pubsub (bug tracking etc) will remain on SF.net but this will make it easy for me to release pubsub to wxpython (i'll just push latest SVN to github), and for wxpython developers to pull it when needed.

Why would you keep SVN?  If you like to stay on sourceforge, which makes sense as people know that the project is there, just use their git offering and keep SVN in read only for a bit and then drop it - or am I missing something.

P.s. the doc standards link is wrong, can you resend

http://wxpython.org/Phoenix/docs/html/DocstringsGuidelines.html

Or via the main page about half way down.
http://wxpython.org/Phoenix/docs/html/main.html

On Fri, Feb 14, 2014 at 1:00 AM, oliver <oliver.s...@gmail.com> wrote:

Hi Werner, I appreciate the offer but again this seems like a big duplication of effort, the users should be referred to pubsub.sourceforge.net, is structured correctly (only exposes what typical/power user would need, but not the guts like core), examples and such  The core should not be documented for wxpython users. So all that work you are doing or wishing has already been done. Let's find another way to handle this.

Why would you want to show less/different information to a wxPython user of pubsub compared to another user?

What I suggest is not causing any duplication, the Sphinx generator which Andrea Gavana has done for the wxPython Phoenix project reads all the doc strings from the different modules, e.g. wx.lib.pubsub and then does a little bit of massaging.  It would probably be more work if 'wx.lib.pubsub' needs a different treatment compared to e.g. 'wx.lib.floatcanvas' another external living in the wx.lib space.

In other words I suggest to make small changes to the pubsub doc strings, e.g. taking pubsub.__init__ as an example change it from:

"""
Pubsub package initialization.

:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
:license: BSD, see LICENSE_BSD_Simple.txt for details.
"""

To:
"""
The Pubsub package provides a publish - subscribe Python API that facilitates event-based programming. Using the publish - subscribe pattern in your application can dramatically simplify its design and improve testability.

Usage
=====

Sample usage::

"""
One listener is subscribed to a topic called 'rootTopic'.
One 'rootTopic' message gets sent. 
"""

from pubsub import pub

# ------------ create a listener ------------------

def listener1(arg1, arg2=None):
    print 'Function listener1 received:'
    print '  arg1 =', arg1
    print '  arg2 =', arg2

# ------------ register listener ------------------

pub.subscribe(listener1, 'rootTopic')

#---------------- send a message ------------------

print 'Publish something via pubsub'
anObj = dict(a=456, b='abc')
pub.sendMessage('rootTopic', arg1=123, arg2=anObj)

:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
:license: BSD, see LICENSE_BSD_Simple.txt for details.
"""

This would improve this page:
wxpython.org/Phoenix/docs/html/lib.pubsub.html

In other words each module.__doc__ should have a short intro of that module which shows up in the respective "Modules Summary" and on the respective "Modules" page.

I don't think that these changes would have a negative effect on the 'internal' pubsub documentation.

Werner

Oliver

On Wed, Feb 12, 2014 at 8:11 AM, Werner <wern...@gmx.ch> wrote:

Hi,

Any plans to adapt more Phoenix style doc strings?

Especially the module doc strings should be enhanced to make listings like this nicer and more usefull.

http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.html#module-lib.pubsub.core

The initial page:

http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

would be nice to be updated and to include a sample or two on how to use pubsub, or maybe even having some samples.

The doc standard used is explained here:
http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

I would be willing to help on this effort and could provide e.g. pull requests or if you stay on SVN patches - but it would be nice if you moved to git (http://sourceforge.net/p/forge/documentation/Git/#management) when you have a spare moment:-) .

Werner

--
You received this message because you are subscribed to the Google Groups "pypubsub" group.

To unsubscribe from this group and stop receiving emails from it, send an email to pypubsub+u...@googlegroups.com.

To post to this group, send email to pypu...@googlegroups.com.
Visit this group at http://groups.google.com/group/pypubsub.
For more options, visit https://groups.google.com/groups/opt_out.

--

Oliver

Contributor to Open Source: PyPubSub, Lua-iCxx, iof

Contributor to StackOverflow

--

Oliver

Contributor to Open Source: PyPubSub, Lua-iCxx, iof

Contributor to StackOverflow

--
You received this message because you are subscribed to the Google Groups "pypubsub" group.

To unsubscribe from this group and stop receiving emails from it, send an email to pypubsub+u...@googlegroups.com.

[Oliver]

Hi Werner, sorry for some reason I never got notice of these postings and relied on notification in my gmail as I don't check the forum's website very often. In any case, is the below still an issue? It will complicate things. I would rather put links at the module level, this way it is one extra click and no duplication. 

[Werner]

Hi Oliver,

On 5/4/2015 23:40, Oliver wrote:

Hi Werner, sorry for some reason I never got notice of these postings and relied on notification in my gmail as I don't check the forum's website very often. In any case, is the below still an issue? It will complicate things. I would rather put links at the module level, this way it is one extra click and no duplication.

Was away for a bit, sorry for late reply.

I still feel it would be nice to see more of a description instead of the 'copyright/license' text on the pages mentioned below.  Not sure if a link alone would do that, but maybe just have some short description and a link.

Werner

On Wednesday, 12 February 2014 08:11:14 UTC-5, werner wrote:

Hi,

Any plans to adapt more Phoenix style doc strings?

Especially the module doc strings should be enhanced to make listings
like this nicer and more usefull.

http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.html#module-lib.pubsub.core

The initial page:

http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

would be nice to be updated and to include a sample or two on how to use
pubsub, or maybe even having some samples.

The doc standard used is explained here:
http://wxpython.org/Phoenix/docs/html/lib.pubsub.html

I would be willing to help on this effort and could provide e.g. pull
requests or if you stay on SVN patches - but it would be nice if you
moved to git
(http://sourceforge.net/p/forge/documentation/Git/#management) when you
have a spare moment:-) .

Werner

--

You received this message because you are subscribed to the Google Groups "pypubsub" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pypubsub+u...@googlegroups.com.
To post to this group, send email to pypu...@googlegroups.com.
Visit this group at http://groups.google.com/group/pypubsub.

For more options, visit https://groups.google.com/d/optout.

[oliver]

Ok I'll add something and you can tell me if that fits