Sphinxed Phoenix Documentation (6)

[Andrea Gavana]

Hi All,

as an Easter present, I am happy to release a new set of
documentation pages for Phoenix, which is available here:

http://xoomer.virgilio.it/infinity77/Phoenix/main.html

I have managed to run the whole of Phoenix, wx.lib, wx.py and wx.tools
via Sphinx - basically everything we have in wxPython.

Also, most (if not all) the Epydoc docstring hyperlinks which are
present in Editra, XRCed and in some place else (i.e., the ones with
L{something}, U{something}, C{something} and so on) are automatically
handled by the docstrings scanner, so you will see most of them
converted to proper links in the HTML documentation.

Werner, I have updated the I18N sample to the latest specs.

There is still some work to do, of course, especially on improving the
docstrings themselves in wx.lib and wx.tools. Editra is well
documented but the automatic sphinx_generator tool can't possibly
convert, without sometimes failing, docstrings that are meant for
Doxygen to Sphinx-compliant ones.

Cody, do you mind me making some slight changes to the docstrings in
Editra or will you prefer a patch against the latest SVN version?

In any case, I think the overall result is good (and with only 70
warnings from Sphinx...). Please let me know if you find anything
strange, and also your thoughts on possible modifications, additions,
improvements and change of documentation strategy you may have. I also
hope Robin will be back soon on wxPython-dev to share some thoughts
about this.

Happy Easter to everyone!

Andrea.

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

[Cody]

Hi,

On Sat, Apr 7, 2012 at 5:16 PM, Andrea Gavana <andrea...@gmail.com> wrote:
> Werner, I have updated the I18N sample to the latest specs.
>
> There is still some work to do, of course, especially on improving the
> docstrings themselves in wx.lib and wx.tools. Editra is well
> documented but the automatic sphinx_generator tool can't possibly
> convert, without sometimes failing, docstrings that are meant for
> Doxygen to Sphinx-compliant ones.
>
> Cody, do you mind me making some slight changes to the docstrings in
> Editra or will you prefer a patch against the latest SVN version?
>

Sorry been swamped lately and haven't had time to keep up with this
work in recent months.

What kind of changes would be needed? Don't really want to make too
many changes as there are a huge amount of documentation and I have my
converter scripts for epydoc to doxygen working fairly satisfactory at
the moment.

Not sure how much we should worry about having the Editra
documentation fully generated as part of the wxPython documentation
either as it is an application and not really part of the library.

Anyway let me know what is needed and I will do what I can.

Cody

[Robin Dunn]

On 4/7/12 3:16 PM, Andrea Gavana wrote:

> There is still some work to do, of course, especially on improving the
> docstrings themselves in wx.lib and wx.tools. Editra is well
> documented but the automatic sphinx_generator tool can't possibly
> convert, without sometimes failing, docstrings that are meant for
> Doxygen to Sphinx-compliant ones.
>
> Cody, do you mind me making some slight changes to the docstrings in
> Editra or will you prefer a patch against the latest SVN version?

Actually I've been thinking of pulling XRCed and Editra out of the
wx.tools package for Phoenix. Instead they will likely be moved to the
root of the Phoenix source dir and will be installed in a more
standalone manner.

So in other words, there is probably not much need to make sure that
they can be documented the same as the rest of the wx package. Maybe we
should just have an overview pages for XRCed and let Editra stand on its
own since it already has lots of docs.

--
Robin Dunn
Software Craftsman
http://wxPython.org

[Andrea Gavana]

I thought the docs would have the same overall structure of the
existing "new wxPyDocs" on the website. I'll stand corrected.

>> On 4/7/12 3:17 PM, nor...@wxsite.net wrote:
>> # The SVN revision of wxWidgets/Phoenix used to build the Sphinx docs.
>> # There must be a more intelligent way to get this information automatically.
>> -SVN_REVISION = '71066'
>>
>>
> import subprocess
> svn_result = subprocess.Popen(["svn", "info"], stdout=subprocess.PIPE).communicate()[0]
> REV = 'unknown'
> for line in svn_result.split("\n"):
> if line.startswith("Revision"):
> REV = line.split(":")[-1].strip()
> break
>
> # Do something with REV, like write it to constants.py

Added in SVN.