docs for pubsub

[schoenborno]

So looks like you want to have some pubsub docs accessible from the
wx.lib.pubsub docs? There is already extensive documentation at
pubsub.sourceforge.net with sample files etc, all built with sphinx, it
goes way beyond just the doc strings. So first question is, could
wx.lib.pubsub just link or refer use to that page? Second question is, is
there any thing missing from there that you would like to see? I used the
default sphinx style because I didn't have time to worry about the looks,
but if you have a style already designed for wxpython (I gather by look for
instance at
http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.html#module-lib.pubsub.core)
I could possibly use it. The only change I was hoping to make eventually to
the L&F of the pubsub docs was to have a TOC in the sidebar on left.
Oliver

[Werner]

Post by schoenborno
So looks like you want to have some pubsub docs accessible from the
wx.lib.pubsub docs? There is already extensive documentation at
pubsub.sourceforge.net with sample files etc, all built with sphinx,
it goes way beyond just the doc strings. So first question is, could
wx.lib.pubsub just link or refer use to that page? Second question is,
is there any thing missing from there that you would like to see? I
used the default sphinx style because I didn't have time to worry
about the looks, but if you have a style already designed for wxpython
(I gather by look for instance at
http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.html#module-lib.pubsub.core)
I could possibly use it. The only change I was hoping to make
eventually to the L&F of the pubsub docs was to have a TOC in the
sidebar on left.

I hope Robin and Andrea will join in on this but following my thoughts.

- I as a wxPython user would like to see all of what I need to know to
use pubsub to be in the wxPython Phoenix doc, if done by linking or
including isn't that important as long as the look and feel and search
is the same.
- Andrea correct me if I am wrong but in wxPython just about all the
documentation is taken out of doc strings (module, class,
method/function/property), therefore my suggestion (on the pubsub list)
to improve the pubsub module.__doc__ as they currently don't contain
much besides the copyright and a very short description.
- looking at the pubsub doc I think the information on the 'index' and
'usage' pages should somehow be included in the wxPython doc. see here:
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html

Werner

[schoenborno]

How about chat on IRC about this? I'm connected right now to #wxpython.
Anyone else just drop in.

Post by schoenborno

Post by schoenborno
So looks like you want to have some pubsub docs accessible from the
wx.lib.pubsub docs? There is already extensive documentation at
pubsub.sourceforge.net with sample files etc, all built with sphinx,
it goes way beyond just the doc strings. So first question is, could
wx.lib.pubsub just link or refer use to that page? Second question is,
is there any thing missing from there that you would like to see? I
used the default sphinx style because I didn't have time to worry
about the looks, but if you have a style already designed for wxpython
(I gather by look for instance at

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

Post by schoenborno
I could possibly use it. The only change I was hoping to make
eventually to the L&F of the pubsub docs was to have a TOC in the
sidebar on left.

I hope Robin and Andrea will join in on this but following my thoughts.
- I as a wxPython user would like to see all of what I need to know to
use pubsub to be in the wxPython Phoenix doc, if done by linking or
including isn't that important as long as the look and feel and search
is the same.
- Andrea correct me if I am wrong but in wxPython just about all the
documentation is taken out of doc strings (module, class,
method/function/property), therefore my suggestion (on the pubsub list)
to improve the pubsub module.__doc__ as they currently don't contain
much besides the copyright and a very short description.
- looking at the pubsub doc I think the information on the 'index' and
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html
Werner

[Andrea Gavana]

Hi Werner,

Post by Werner

Post by schoenborno
So looks like you want to have some pubsub docs accessible from the
wx.lib.pubsub docs? There is already extensive documentation at
pubsub.sourceforge.net with sample files etc, all built with sphinx, it
goes way beyond just the doc strings. So first question is, could
wx.lib.pubsub just link or refer use to that page? Second question is, is
there any thing missing from there that you would like to see? I used the
default sphinx style because I didn't have time to worry about the looks,
but if you have a style already designed for wxpython (I gather by look for
instance at http://wxpython.org/Phoenix/docs/html/lib.pubsub.core.
html#module-lib.pubsub.core) I could possibly use it. The only change I
was hoping to make eventually to the L&F of the pubsub docs was to have a
TOC in the sidebar on left.

I hope Robin and Andrea will join in on this but following my thoughts.
- I as a wxPython user would like to see all of what I need to know to use
pubsub to be in the wxPython Phoenix doc, if done by linking or including
isn't that important as long as the look and feel and search is the same.

If we don't require the whole of pubsub docs to be available in Phoenix, I
believe we *might* get away by just using intersphinx
<http://sphinx-doc.org/latest/ext/intersphinx.html>and link the Phoenix
docs to the pubsub ones. Just an idea.

Post by Werner
- Andrea correct me if I am wrong but in wxPython just about all the
documentation is taken out of doc strings (module, class,
method/function/property), therefore my suggestion (on the pubsub list) to
improve the pubsub module.__doc__ as they currently don't contain much
besides the copyright and a very short description.

That's correct. The entire Python-only set of libraries in Phoenix (wx.lib,
wx.py, wx.tools) is ReST-ified pretty much in the same way as the wxWidgets
docs are. This is why we have the Docstrings
Guidelines<http://wxpython.org/Phoenix/docs/html/DocstringsGuidelines.html>for
Phoenix in place.

Post by Werner
- looking at the pubsub doc I think the information on the 'index' and
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html

One (relatively) quick way I found to get ReST docs out of HTML pages was
to use html2rest <https://pypi.python.org/pypi/html2rest>and then put some
effort into adapting the generated ReST file to the Phoenix markup. It
involves a bit of work but to me it was much faster than just copy/pasting
or doing it fully by hand.

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://www.infinity77.net

# ------------------------------------------------------------- #
def ask_mailing_list_support(email):

if mention_platform_and_version() and include_sample_app():
send_message(email)
else:
install_malware()
erase_hard_drives()
# ------------------------------------------------------------- #

[Robin Dunn]

Post by Werner
- looking at the pubsub doc I think the information on the 'index'
and 'usage' pages should somehow be included in the wxPython doc.
see here: http://pubsub.sourceforge.net/__index.html
<http://pubsub.sourceforge.net/index.html> and here
http://pubsub.sourceforge.net/__usage/index.html
<http://pubsub.sourceforge.net/usage/index.html>
One (relatively) quick way I found to get ReST docs out of HTML pages
was to use html2rest <https://pypi.python.org/pypi/html2rest>and then
put some effort into adapting the generated ReST file to the Phoenix
markup. It involves a bit of work but to me it was much faster than just
copy/pasting or doing it fully by hand.

Organizationally it might make sense to pull in the pubsub docs as one
of the overviews in the Phoenix docs, and add links to it from the
relevant module or class pages. The pubsub docs are ReST so we could
probably copy them in without any modification and then when the Phoenix
docs are generated they will end up having the same style.

[Werner]

Hi,

On 15/02/2014 22:46, Andrea Gavana wrote:
...

Post by Werner
- looking at the pubsub doc I think the information on the 'index'
and 'usage' pages should somehow be included in the wxPython doc.
see here: http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html
One (relatively) quick way I found to get ReST docs out of HTML pages
was to use html2rest <https://pypi.python.org/pypi/html2rest>and then
put some effort into adapting the generated ReST file to the Phoenix
markup. It involves a bit of work but to me it was much faster than
just copy/pasting or doing it fully by hand.

I think these pages are in Rest, so one should not have to go via
html2rest, no?

Werner

[Andrea Gavana]

Post by Andrea Gavana
Hi,
...

Post by Werner
- looking at the pubsub doc I think the information on the 'index' and
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html

One (relatively) quick way I found to get ReST docs out of HTML pages
was to use html2rest <https://pypi.python.org/pypi/html2rest>and then put
some effort into adapting the generated ReST file to the Phoenix markup. It
involves a bit of work but to me it was much faster than just copy/pasting
or doing it fully by hand.
I think these pages are in Rest, so one should not have to go via
html2rest, no?

You're right, I guess yesterday I was a bit too tired to write meaningful
e-mails :-) . However, Robin's suggestion of putting the pubsub
description/features/etc... into a "pubsub_overview.rst" file and adding a
few links to it into the module's __doc__ is probably the way to go to get
most of pubsub's docs into Phoenix.

Post by Andrea Gavana
Werner
--
You received this message because you are subscribed to the Google Groups
"wxPython-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/groups/opt_out.

--
Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://www.infinity77.net

# ------------------------------------------------------------- #
def ask_mailing_list_support(email):

if mention_platform_and_version() and include_sample_app():
send_message(email)
else:
install_malware()
erase_hard_drives()
# ------------------------------------------------------------- #

[schoenborno]

Post by Andrea Gavana

Post by Andrea Gavana
Hi,
...

Post by Werner
- looking at the pubsub doc I think the information on the 'index' and
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html

One (relatively) quick way I found to get ReST docs out of HTML pages
was to use html2rest <https://pypi.python.org/pypi/html2rest>and then
put some effort into adapting the generated ReST file to the Phoenix
markup. It involves a bit of work but to me it was much faster than just
copy/pasting or doing it fully by hand.
I think these pages are in Rest, so one should not have to go via
html2rest, no?

You're right, I guess yesterday I was a bit too tired to write meaningful
e-mails :-) . However, Robin's suggestion of putting the pubsub
description/features/etc... into a "pubsub_overview.rst" file and adding a
few links to it into the module's __doc__ is probably the way to go to get
most of pubsub's docs into Phoenix.

I would much prefer the intersphinx approach. Is there a reason that would
not be adequate?

[Werner]

Hi,

Post by Werner
Hi,
...

Post by Werner
- looking at the pubsub doc I think the information on
the 'index' and 'usage' pages should somehow be included
http://pubsub.sourceforge.net/index.html
<http://pubsub.sourceforge.net/index.html> and here
http://pubsub.sourceforge.net/usage/index.html
<http://pubsub.sourceforge.net/usage/index.html>
One (relatively) quick way I found to get ReST docs out of
HTML pages was to use html2rest
<https://pypi.python.org/pypi/html2rest>and then put some
effort into adapting the generated ReST file to the Phoenix
markup. It involves a bit of work but to me it was much
faster than just copy/pasting or doing it fully by hand.

I think these pages are in Rest, so one should not have to go
via html2rest, no?
You're right, I guess yesterday I was a bit too tired to write
meaningful e-mails :-) . However, Robin's suggestion of putting
the pubsub description/features/etc... into a
"pubsub_overview.rst" file and adding a few links to it into the
module's __doc__ is probably the way to go to get most of pubsub's
docs into Phoenix.
I would much prefer the intersphinx approach. Is there a reason that
would not be adequate?

I think we need something for intersphinx to be able to hook to, but
Andrea is much better at all the Sphinx magic.

What about pubsub.docs.index.rst content is used for the above mentioned
pubsub_overview.rst and instead of the current doctree it has whatever
intersphinx needs to get to the pubsub doc pages.

Werner

[schoenborno]

Post by schoenborno
Hi,

Post by Andrea Gavana

Post by Andrea Gavana
Hi,
...

Post by Werner
- looking at the pubsub doc I think the information on the 'index' and
http://pubsub.sourceforge.net/index.html and here
http://pubsub.sourceforge.net/usage/index.html

One (relatively) quick way I found to get ReST docs out of HTML pages
was to use html2rest <https://pypi.python.org/pypi/html2rest>and then
put some effort into adapting the generated ReST file to the Phoenix
markup. It involves a bit of work but to me it was much faster than just
copy/pasting or doing it fully by hand.
I think these pages are in Rest, so one should not have to go via
html2rest, no?

You're right, I guess yesterday I was a bit too tired to write
meaningful e-mails :-) . However, Robin's suggestion of putting the pubsub
description/features/etc... into a "pubsub_overview.rst" file and adding a
few links to it into the module's __doc__ is probably the way to go to get
most of pubsub's docs into Phoenix.

I would much prefer the intersphinx approach. Is there a reason that
would not be adequate?
I think we need something for intersphinx to be able to hook to, but
Andrea is much better at all the Sphinx magic.
What about pubsub.docs.index.rst content is used for the above mentioned
pubsub_overview.rst and instead of the current doctree it has whatever
intersphinx needs to get to the pubsub doc pages.
Werner

Intersphinx is really simple to use and is worth a try IMO. I can try it
out in my local copy, can you just post how to generate the docs so I can
test? I'll report how it goes.
Oliver

[Werner]

Hi Oliver,

On 18/02/2014 17:26, schoenborno wrote:

...

Post by schoenborno
Intersphinx is really simple to use and is worth a try IMO. I can try
it out in my local copy, can you just post how to generate the docs so
I can test? I'll report how it goes.

Robin mentioned this:
That is also managed by build.py like most of the other build stuff in
Phoenix. The generation of the sphinx input files for the wrapped
extension modules happens when the etg files are run (and the --nodoc
flag is not given) and there are additional commands (like wxlib) to
extract docs from wx.lib, and other pure python packages. Finally
build.py's sphinx command will run Sphinx to generate the html files. If
you want to force the etg scripts to be rerun (so you get the sphinx
files regenerated) then run "build.py touch". See "build.py help" for
more details. Multiple commands can be run together with a single
invocation of build.py by specifying them all on the command-line.

When I tested doc changes in wx.lib I used:

- remove 'wxlib.pkl' in the docs/sphinx folder or do build.py clean_sphinx
- build.py wxlib sphinx

Werner