[Graphviz] building doc with Python3

wxPython Dev
1

I fixing the build-scripts to create the doc files with Python3
(currently this doesn't work).

I have a problem with the graph-creating part of it. It uses the
command "dot" from the Graphviz-package (it is installed).
"dot" doesn't generated the requested files and the build script stop
because of that. Nothing is generated in the specified folder.

I put in some debug-print-calls in the code. The
arguments list looks ok for me. I only wonder about the missing space
(' ') between the '-o' and the filename. But a space doesn't solve the
problem.

This is the output. Please keep in mind this runs on Python3. Log for
the "dot_args". Ok, or not?

[bash]
Build using: "/usr/bin/python3"
3.4.0 (default, Apr 11 2014, 13:05:18)
[GCC 4.8.2]
Python's architecture is 32bit
cfg.VERSION: 3.0.3

USING VERSION: 3.0.3.dev1660+b7b9635

Running command: wx.lib

ReST-ifying lib...

    - lib.agw (package)
       - lib.agw.aui (package)
          - lib.agw.aui.aui_constants (module)
          - lib.agw.aui.aui_switcherdialog (module)
== code ==
digraph dummy {
ratio=auto;
size="";
rankdir=TB;
fontsize=9;
  "Window" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "WindowBase" ->
      "Window" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color="#23238E"];
      "Trackable" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "WindowBase" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "EvtHandler" ->
      "WindowBase" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color="#23238E"];
      "EvtHandler" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "Object" ->
      "EvtHandler" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color="#23238E"];
      "Trackable" ->
      "EvtHandler" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color="#23238E"];
      "Object" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "aui_switcherdialog.MultiColumnListCtrl" [align=center,style=bold,color=blue,height=0.3,fontsize=10,URL="lib.agw.aui.aui_switcherdialog.MultiColumnListCtrl.html",shape=box,fontcolor=black,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "Control" ->
      "aui_switcherdialog.MultiColumnListCtrl" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color=red];
      "Control" [align=center,style="setlinewidth(0.5)",height=0.3,fontsize=10,shape=box,fontcolor=grey45,labelloc=c,fontname=Vera
      Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans];
      "Window" ->
      "Control" [arrowsize=0.5,arrowtail=open,style="setlinewidth(0.5)",dir=back,color="#23238E"]; }

============ DOT ===============
== dot_args ==
['dot', '-Tpng',
'-o/home/user/share/work/Phoenix/docs/sphinx/_static/images/inheritance/lib.agw.aui.aui_switcherdialog.MultiColumnListCtrl_inheritance.png',
'-Tcmapx',
'-o/home/user/share/work/Phoenix/docs/sphinx/_static/images/inheritance/lib.agw.aui.aui_switcherdialog.MultiColumnListCtrl_inheritance.png.map']
Traceback (most recent call last): File "./build.py", line 1616, in
<module> main(sys.argv[1:]) File "./build.py", line 169, in main
function(options, args) File "./build.py", line 828, in cmd_wxlib
    ModuleHunter(init_name, import_name, version)
  File "/home/user/share/work/Phoenix/sphinxtools/modulehunter.py",
line 606, in ModuleHunter ToRest(import_name)
  File "/home/user/share/work/Phoenix/sphinxtools/modulehunter.py",
line 597, in ToRest library_class.Walk(library_class, class_summary)
  File
"/home/user/share/work/Phoenix/sphinxtools/librarydescription.py", line
442, in Walk self.Walk(child, class_summary) File
"/home/user/share/work/Phoenix/sphinxtools/librarydescription.py", line
442, in Walk self.Walk(child, class_summary) File
"/home/user/share/work/Phoenix/sphinxtools/librarydescription.py", line
442, in Walk self.Walk(child, class_summary) File
"/home/user/share/work/Phoenix/sphinxtools/librarydescription.py", line
439, in Walk child.ToRest(class_summary) File
"/home/user/share/work/Phoenix/sphinxtools/librarydescription.py", line
733, in ToRest png, map =
self.inheritance_diagram.MakeInheritanceDiagram(class_summary) File
"/home/user/share/work/Phoenix/sphinxtools/inheritance.py", line 301,
in MakeInheritanceDiagram fid = open(mapfile, 'rt') FileNotFoundError:
[Errno 2] No such file or directory:
'/home/user/share/work/Phoenix/docs/sphinx/_static/images/inheritance/lib.agw.aui.aui_switcherdialog.MultiColumnListCtrl_inheritance.png.map'
Finished command: wx.lib (0m1.859s)
[/bash]

I can not see a dot-error-output here. And I don't know how to catch it
if there would be some.

2

Got the error (but didn't understand).

print(stderr)
"b"Warning: <stdin>: syntax error in line 6 near ','\n"

I can not see any difference between line 6 and the other lines of dot
input string.

···

On 2015-02-25 01:28 <moonkid@posteo.org> wrote:

I can not see a dot-error-output here. And I don't know how to catch
it if there would be some.

3

moonkid@posteo.org wrote:

···

On 2015-02-25 01:28<moonkid@posteo.org> wrote:

I can not see a dot-error-output here. And I don't know how to catch
it if there would be some.

Got the error (but didn't understand).

print(stderr)
"b"Warning:<stdin>: syntax error in line 6 near ','\n"

I can not see any difference between line 6 and the other lines of dot
input string.

The first thing I would do is try running dot with that same input from the command-line to ensure I get the same error (so then I can be sure that I have the correct snippet of code.) Then fiddle with the code a bit to see if I can isolate the cause. If that doesn't work then the next step would be to build with Python2.7 and compare the generated dot code and see what is different.

--
Robin Dunn
Software Craftsman

4

Found the problem and beside of it a dot-bug with it. The bug is still
fixed in the current dot-version (but my ubuntu is to old).

There are more than one font names. But there is no " around them.
e.g. font=Arial, Helvetica, ...
should be
font="Arial, Helvetica, ..."

Then it works from there on. But I ask myself why this script work for
other people? Maybe the newest dot-version (2.38) handle this without
problems instead of my 2.36 (in Ubuntu 14.04.2). Anyway this is fixed...

Another "problem". The build script and sphinx run without (any from me
noticed) errors. There are some html-files generated but I miss e.g.
the classes.
e.g. the core classes are missing, they are missing in the index and in
the search result

That is the short output of the build including a module list. Maybe you
can see better that something is missing in that list?

user@MONSTER:~/share/work/Phoenix$ python3 ./build.py wxlib sphinx
Build using: "/usr/bin/python3"
3.4.0 (default, Apr 11 2014, 13:05:18)
[GCC 4.8.2]
Python's architecture is 32bit
cfg.VERSION: 3.0.3

USING VERSION: 3.0.3.dev1660+b7b9635

Running command: wx.lib

ReST-ifying lib...

    - lib.agw (package)
       - lib.agw.aui (package)
          - lib.agw.aui.aui_constants (module)
          - lib.agw.aui.aui_switcherdialog (module)
          - lib.agw.aui.aui_utilities (module)
          - lib.agw.aui.auibar (module)
          - lib.agw.aui.auibook (module)
          - lib.agw.aui.dockart (module)
          - lib.agw.aui.framemanager (module)
          - lib.agw.aui.tabart (module)
          - lib.agw.aui.tabmdi (module)
       - lib.agw.persist (package)
          - lib.agw.persist.persist_constants (module)
          - lib.agw.persist.persist_handlers (module)
          - lib.agw.persist.persistencemanager (module)
       - lib.agw.ribbon (package)
          - lib.agw.ribbon.art (module)
          - lib.agw.ribbon.art_aui (module)
          - lib.agw.ribbon.art_default (module)
          - lib.agw.ribbon.art_internal (module)
          - lib.agw.ribbon.art_msw (module)
          - lib.agw.ribbon.art_osx (module)
          - lib.agw.ribbon.bar (module)
          - lib.agw.ribbon.buttonbar (module)
          - lib.agw.ribbon.control (module)
          - lib.agw.ribbon.gallery (module)
          - lib.agw.ribbon.page (module)
          - lib.agw.ribbon.panel (module)
          - lib.agw.ribbon.toolbar (module)
       - lib.agw.advancedsplash (module)
       - lib.agw.aquabutton (module)
       - lib.agw.artmanager (module)
       - lib.agw.balloontip (module)
       - lib.agw.buttonpanel (module)
       - lib.agw.cubecolourdialog (module)
       - lib.agw.customtreectrl (module)
       - lib.agw.flatmenu (module)
       - lib.agw.flatnotebook (module)
       - lib.agw.floatspin (module)
       - lib.agw.fmcustomizedlg (module)
       - lib.agw.fmresources (module)
       - lib.agw.foldpanelbar (module)
       - lib.agw.fourwaysplitter (module)
       - lib.agw.genericmessagedialog (module)
       - lib.agw.gradientbutton (module)
       - lib.agw.hyperlink (module)
       - lib.agw.hypertreelist (module)
       - lib.agw.infobar (module)
       - lib.agw.knobctrl (module)
       - lib.agw.labelbook (module)
       - lib.agw.multidirdialog (module)
       - lib.agw.peakmeter (module)
       - lib.agw.piectrl (module)
       - lib.agw.pybusyinfo (module)
       - lib.agw.pycollapsiblepane (module)
       - lib.agw.pygauge (module)
       - lib.agw.pyprogress (module)
       - lib.agw.rulerctrl (module)
       - lib.agw.shortcuteditor (module)
       - lib.agw.speedmeter (module)
       - lib.agw.supertooltip (module)
       - lib.agw.thumbnailctrl (module)
       - lib.agw.toasterbox (module)
       - lib.agw.ultimatelistctrl (module)
       - lib.agw.xlsgrid (module)
       - lib.agw.zoombar (module)
    - lib.art (package)
       - lib.art.flagart (module)
       - lib.art.img2pyartprov (module)
    - lib.floatcanvas (package)
       - lib.floatcanvas.Utilities (package)
          - lib.floatcanvas.Utilities.Colors (module)
       - lib.floatcanvas.FCEvents (module)
       - lib.floatcanvas.Resources (module)
       - lib.floatcanvas.ScreenShot (module)
    - lib.masked (package)
       - lib.masked.combobox (module)
       - lib.masked.ctrl (module)
       - lib.masked.ipaddrctrl (module)
       - lib.masked.maskededit (module)
       - lib.masked.numctrl (module)
       - lib.masked.textctrl (module)
       - lib.masked.timectrl (module)
    - lib.mixins (package)
       - lib.mixins.grid (module)
       - lib.mixins.gridlabelrenderer (module)
       - lib.mixins.imagelist (module)
       - lib.mixins.inspection (module)
       - lib.mixins.listctrl (module)
       - lib.mixins.rubberband (module)
       - lib.mixins.treemixin (module)
    - lib.ogl (package)
       - lib.ogl.basic (module)
       - lib.ogl.bmpshape (module)
       - lib.ogl.canvas (module)
       - lib.ogl.composit (module)
       - lib.ogl.diagram (module)
       - lib.ogl.divided (module)
       - lib.ogl.drawn (module)
       - lib.ogl.lines (module)
       - lib.ogl.oglmisc (module)
    - lib.pubsub (package)
       - lib.pubsub.core (package)
          - lib.pubsub.core.callables (module)
          - lib.pubsub.core.datamsg (module)
          - lib.pubsub.core.imp2 (module)
          - lib.pubsub.core.itopicdefnprovider (module)
          - lib.pubsub.core.listener (module)
          - lib.pubsub.core.listenerbase (module)
          - lib.pubsub.core.listenerimpl (module)
          - lib.pubsub.core.notificationmgr (module)
          - lib.pubsub.core.publisher (module)
          - lib.pubsub.core.publisherbase (module)
          - lib.pubsub.core.publishermixin (module)
          - lib.pubsub.core.topicargspec (module)
          - lib.pubsub.core.topicargspecimpl (module)
          - lib.pubsub.core.topicdefnprovider (module)
          - lib.pubsub.core.topicexc (module)
          - lib.pubsub.core.topicmgr (module)
          - lib.pubsub.core.topicmgrimpl (module)
          - lib.pubsub.core.topicobj (module)
          - lib.pubsub.core.topictreetraverser (module)
          - lib.pubsub.core.topicutils (module)
          - lib.pubsub.core.treeconfig (module)
          - lib.pubsub.core.validatedefnargs (module)
          - lib.pubsub.core.weakmethod (module)
       - lib.pubsub.utils (package)
          - lib.pubsub.utils.exchandling (module)
          - lib.pubsub.utils.misc (module)
          - lib.pubsub.utils.notification (module)
          - lib.pubsub.utils.topictreeprinter (module)
          - lib.pubsub.utils.xmltopicdefnprovider (module)
       - lib.pubsub.policies (module)
       - lib.pubsub.pub (module)
       - lib.pubsub.py2and3 (module)
       - lib.pubsub.setuparg1 (module)
       - lib.pubsub.setupkwargs (module)
    - lib.anchors (module)
    - lib.busy (module)
    - lib.buttons (module)
    - lib.calendar (module)
    - lib.CDate (module)
    - lib.ClickableHtmlWindow (module)
    - lib.colourdb (module)
    - lib.colourselect (module)
    - lib.colourutils (module)
    - lib.combotreebox (module)
    - lib.delayedresult (module)
    - lib.dialogs (module)
    - lib.docview (module)
    - lib.dragscroller (module)
    - lib.embeddedimage (module)
    - lib.eventStack (module)
    - lib.eventwatcher (module)
    - lib.evtmgr (module)
    - lib.expando (module)
    - lib.fancytext (module)
    - lib.filebrowsebutton (module)
    - lib.floatbar (module)
    - lib.foldmenu (module)
    - lib.gestures (module)
    - lib.gridmovers (module)
    - lib.imagebrowser (module)
    - lib.imageutils (module)
    - lib.infoframe (module)
    - lib.inspection (module)
    - lib.itemspicker (module)
    - lib.langlistctrl (module)
    - lib.layoutf (module)
    - lib.msgpanel (module)
    - lib.multisash (module)
    - lib.mvctree (module)
    - lib.newevent (module)
    - lib.nvdlg (module)
    - lib.pdfwin (module)
    - lib.platebtn (module)
    - lib.popupctl (module)
    - lib.printout (module)
    - lib.progressindicator (module)
    - lib.pydocview (module)
    - lib.rcsizer (module)
    - lib.resizewidget (module)
    - lib.scrolledpanel (module)
    - lib.sheet (module)
    - lib.six (module)
    - lib.sized_controls (module)
    - lib.softwareupdate (module)
    - lib.splitter (module)
    - lib.statbmp (module)
    - lib.stattext (module)
    - lib.throbber (module)
    - lib.ticker (module)
    - lib.ticker_xrc (module)
    - lib.utils (module)
    - lib.wordwrap (module)
    - lib.wxpTag (module)
Finished command: wx.lib (0m9.966s)
Running command: sphinx
sphinx-build -b html
      -d /home/user/share/work/Phoenix/docs/sphinx/build/doctrees . /home/user/share/work/Phoenix/docs/html
      Running Sphinx v1.2.2 loading pickled environment... done
building [html]: targets for 895 source files that are out of date
updating environment: 0 added, 853 changed, 0 removed

···

On 2015-02-24 19:10 Robin Dunn <robin@alldunn.com> wrote:

> "b"Warning:<stdin>: syntax error in line 6 near ','\n"

5

moonkid@posteo.org wrote:

"b"Warning:<stdin>: syntax error in line 6 near ','\n"

Found the problem and beside of it a dot-bug with it. The bug is still
fixed in the current dot-version (but my ubuntu is to old).

There are more than one font names. But there is no " around them.
e.g. font=Arial, Helvetica, ...
should be
font="Arial, Helvetica, ..."

Then it works from there on. But I ask myself why this script work for
other people? Maybe the newest dot-version (2.38) handle this without
problems instead of my 2.36 (in Ubuntu 14.04.2). Anyway this is fixed...

Another "problem". The build script and sphinx run without (any from me
noticed) errors. There are some html-files generated but I miss e.g.
the classes.
e.g. the core classes are missing, they are missing in the index and in
the search result

That is the short output of the build including a module list. Maybe you
can see better that something is missing in that list?

user@MONSTER:~/share/work/Phoenix$ python3 ./build.py wxlib sphinx

You also need to run the dox command and the etg command (without the --nodoc flag) in order to get the files that the sphinx command will process. And since the wx.lib files are imported as part of the docstring scan you will need to have a built wxPython in place, so you will need to have run the build command at least once in the past.

For the record, this is the build.py command line run by the buildbot slave building the documentation and source:

cmd = 'python -u build.py %s setrev dox touch etg sip build wxlib wxtools wxpy ' \
       'sphinx docs_bdist sdist --upload' % pyVer

···

On 2015-02-24 19:10 Robin Dunn<robin@alldunn.com> wrote:

--
Robin Dunn
Software Craftsman

6

Not sure if I understand you correct. Doesn't work because of a problem
with doxygen. The file/path
"/home/user/share/work/Phoenix/ext/wxWidgets/docs/doxygen"
is missing.

python3 ./build.py wxlib setrev dox

etg sphinx Build using: "/usr/bin/python3"
3.4.0 (default, Apr 11 2014, 13:05:18)
[GCC 4.8.2]
Python's architecture is 32bit
cfg.VERSION: 3.0.3.dev1684+6933551

USING VERSION: 3.0.3.dev1684+6933551

Running command: wx.lib

ReST-ifying lib...

    - lib.agw (package)
       - lib.agw.aui (package)
[SNIP]
Finished command: wx.lib (0m4.501s)
Running command: setrev
REV.txt set to ".dev1684+6933551"
cfg.VERSION: 3.0.3.dev1684+6933551
Finished command: setrev (0.110s)
Running command: dox
Checking for /home/user/share/work/Phoenix/bin/doxygen-1.8.2-linux...
Traceback (most recent call last):
  File "./build.py", line 1616, in <module>
    main(sys.argv[1:])
  File "./build.py", line 169, in main
    function(options, args)
  File "./build.py", line 671, in cmd_dox
    _doDox('xml')
  File "./build.py", line 664, in _doDox
    pwd = pushDir(posixjoin(wxDir(), 'docs/doxygen'))
  File "./build.py", line 431, in __init__
    os.chdir(newDir)
FileNotFoundError: [Errno 2] No such file or directory:
      '/home/user/share/work/Phoenix/ext/wxWidgets/docs/doxygen'
      Finished command: dox (0.476s)

7

moonkid@posteo.org wrote:

Not sure if I understand you correct. Doesn't work because of a problem
with doxygen. The file/path
"/home/user/share/work/Phoenix/ext/wxWidgets/docs/doxygen"
is missing.

Probably because you forgot to update the submodule again (that's where the wxWidgets source tree lives). Either do this:

   git submodule init # only needs to be done once per clone
   git submodule update # should be done after every pull from upstream

Or just use the daily source tarballs instead of fetching from git.

···

--
Robin Dunn
Software Craftsman

8

I never heard about "submodule" before. Sounds like a nice feauter.
It is for "integrating" external repositories in/with my own, right?

This submodul-stuff should be added to the Wiki-page, too.
<http://wiki.wxpython.org/ContributeWithGIT&gt;

Without it somebody (e.g. me) is not able to work and test
modifications to the documentation.

So doc-build command I used is correct? I will try this night, but my
little machine will take some hours for that.

But the still living question is, where are the doc-files?
e.g. Which file do I need to edit, wenn I modify the Point.Get()
documentation.
Other examples would be Size.Get() and class DateTime.

Thank you very much for all your peoples patience with me.

···

On 2015-02-26 11:39 Robin Dunn <robin@alldunn.com> wrote:

Probably because you forgot to update the submodule again (that's
where the wxWidgets source tree lives). Either do this:

9

Sill no success with that line
"python3 ./build.py wxlib setrev dox sphinx"

There are some elementary parts of the doc missing - e.g. wx.core
Classes.

Of cousre I checked out wxWidgets from git. There is a lot of stuff now
in /Phoenix/ext/wxWidgets/.

build.py --help
don't give me a hint about that.

Maybe this output-warnings about "wxlib" give a hint?
Running command: wx.lib
Message: Importing main library 'lib'...
Message: Main library 'lib-3.0.3' imported...
Message: Importing sub-modules and sub-packages...

WARNING: Unable to import module/package 'lib.activex.activex'.
         Exception was: ValueError: _type_ 'v' not supported

WARNING: Unable to import module/package
'lib.activexwrapper.activexwrapper'. Exception was: ImportError:
ActiveXWrapper requires PythonWin. Please install the PyWin32 package.

And a lot of other Warnings about missing modules (e.g. wxcairo,
winreg, pdfwin).

···

On 2015-02-26 23:51 <moonkid@posteo.org> wrote:

I will try this night, but my
little machine will take some hours for that.

10

This sphinx output is maybe helpfull

Running command: sphinx

WARNING: there are 115 instances of referenced classes/enums, via the
`:ref:` role, which are not in the list of available classes (these may
be classes yet to be ported to Phoenix or C++-specific classes which
will never be ported to Phoenix).

*sphinxgenerator* has replaced the `:ref:` role for them with simple
backticks, i.e.:

    :ref:`MissingClass` ==> `MissingClass`

to avoid warning from Sphinx and Docutils, and saved a list of their
occurrences into the text file "unreferenced_classes.inc" together with
the ReST file names where they appear.

sphinx-build -b html
-d /home/user/share/work/Phoenix/docs/sphinx/build/doctrees . /home/user/share/work/Phoenix/docs/html
Making output directory... Running Sphinx v1.2.2
loading pickled environment... failed: [Errno 2] No such file or
directory:
'/home/user/share/work/Phoenix/docs/sphinx/build/doctrees/environment.pickle'
building [html]: targets for 961 source files that are out of date
updating environment: 961 added, 0 changed, 0 removed

···

On 2015-02-27 02:09 <moonkid@posteo.org> wrote:

Sill no success

11

moonkid@posteo.org wrote:

I will try this night, but my
little machine will take some hours for that.

Sill no success with that line
"python3 ./build.py wxlib setrev dox sphinx"

Ok, one more time: Order matters.

The dox command is what produces the XML files, the etg command processes those files, the sphinx command takes some of the intermediate products of the etg command and runs them through the Sphinx tool to generate the final documentation. So you need to run the commands dox, etg, and sphinx, in that order. If you also want to run wx.lib, wx.py and wx.tools through Sphinx then you can use the wxlib, wxpy and wxtools build commands (and they need to be importable so Phoenix needs to be built for it to work.)

Please read the README file in the root folder, as a lot of this is covered there.

···

On 2015-02-26 23:51<moonkid@posteo.org> wrote:

--
Robin Dunn
Software Craftsman

12

moonkid@posteo.org wrote:

But the still living question is, where are the doc-files?
e.g. Which file do I need to edit, wenn I modify the Point.Get()
documentation.
Other examples would be Size.Get() and class DateTime.

The documentation of the C++ classes comes from wxWidgets/interface/wx. As described in several places, doxygen is used to parse those files into XML and the XML is processed by Phoenix's etg scripts to produce the wrapper generator code and also to generate the ReST files used to produce the documentation. There are also some static, hand-edited files under docs/sphinx/rest_substitutions that are used for things like the overview pages and the example code snippets.

In addition, there are documentation snippets for some things in the etg files themselves. These are usually for custom Python-specific additions to the C++ classes, or to fiddle with the documentation objects coming from the C++ classes (via the XML) like some changes I pushed a few hours ago.

Finally, the pure python modules (like what is in wx.lib) are documented as regular docstrings in the .py files.

···

--
Robin Dunn
Software Craftsman

13

So you need to run the commands dox, etg, and sphinx, in that order.

It is the first time I heard of etg command in the case of producing
docu.

If you also want
to run wx.lib, wx.py and wx.tools through Sphinx

What would be the result of that compared to only "dox etc sphinx"?
Which parts of the docu whould be missing.

About the Point docu:
There is
ext/wxWidgets/interface/wx/gdicmn.h
declaring a 'class wxPoint' with C++ code.

I really understand the wrapping thing and why the docu is wxPhoenix
documentation is extracted form a lot of different places in different
formats from different tools.

But this doesn't help me. In the wxPhoenix docu is a 'Point.Get()'
function described. And of course it is not declared in the gdicmn.h
class because it return a python-tuple.

So what is the way here? Where does this html-file with Point.Get()
inside come from? I just need a file to edit to improve the
documentation of Point.
The etg- and src-directory doesn't contain 'Point'.

Of course I read README.rst but the build.py commands themselfs are not
documented. I currently don't know where Point.Get() comes from because
it is not in the C++ header file and I found no "tweaker" file about it.

···

On 2015-02-26 20:08 Robin Dunn <robin@alldunn.com> wrote:

14

I still go on to build the doc (with 'python3 ./build.py dox etg
sphinx). And I don't forget to run 'cleanall'.

There is a problem I don't understand.
The etg command run etg/htmlwin.py. And this py cause a lot of trouble.

The file
"Phoenix/ext/wxWidgets/docs/doxygen/out/xml/wxHtmlLinkEvent"
doesn't exists. Don't know why or if it is needed.

I modified the code, so that the script goes on and just put out a
message about it.

Then htmlwin.py call a lot of ClassDef.find(). And of course it find
nothing. And find() raises exceptions.

So what should be done?

There is one class missing (don't know why) and the complete build
script crash against the wall. I think this behavior is to much.
There could be warnings or errors and then the script should go on.

What do you think?

15

Maybe this depends on my newer doxygen version (1.8.6)?
I can not test this because the version you are using is not available
at 32bit linux.

And I don't want to build a external tool just to test a maybe-problem.

···

On 2015-02-28 03:02 <moonkid@posteo.org> wrote:

The file
"Phoenix/ext/wxWidgets/docs/doxygen/out/xml/wxHtmlLinkEvent"
doesn't exists. Don't know why or if it is needed.

16

moonkid@posteo.org wrote:

So you need to run the commands dox, etg, and sphinx, in that order.

It is the first time I heard of etg command in the case of producing
docu.

Really? That's not even the first time I mentioned it in this thread. And I'm pretty sure I mentioned it at least once in another message thread last week too.

If you also want
to run wx.lib, wx.py and wx.tools through Sphinx

What would be the result of that compared to only "dox etc sphinx"?
Which parts of the docu whould be missing.

The docs for the modules in the wx.lib, wx.py and wx.tools packages. Isn't that kinda obvious? Especially since the build.py help says:

       wxlib Build the Sphinx input files for wx.lib
       wxpy Build the Sphinx input files for wx.py
       wxtools Build the Sphinx input files for wx.tools

Of course I read README.rst

Um, are you sure?

but the build.py commands themselfs are not
documented.

See the section titled "Important build.py commands" and also run "python build.py --help" as it suggests. And "Use the source Luke!" the answers to all questions are there. Somewhere.

I currently don't know where Point.Get() comes from because
it is not in the C++ header file and I found no "tweaker" file about it.

From the README.rst file:

"""
To help keep things a little easier when looking for things that need to be
worked on, the file names in the Phoenix project will mirror the names of the
files in the wxWidgets interface headers folder. For example, if there is a
interface/wx/FOO.h and we are processing the XML produced for that file then
the ETG script for the classes and other items will be named etg/FOO.py and it
will produce sip/gen/FOO.sip, unit tests will be in unittests/test_FOO.py,
and so on.
"""

So that should lead you to etg/gdicmn.py, which has a section that starts with:

     # wxPoint tweaks
     c = module.find('wxPoint')

and it also has this code a little further on from there:

     c.addCppMethod('PyObject*', 'Get', '()', """\
         return sipBuildResult(0, "(ii)", self->x, self->y);
         """,
         pyArgsString="() -> (x,y)",
         briefDoc="Return the x and y properties as a tuple.")

···

On 2015-02-26 20:08 Robin Dunn<robin@alldunn.com> wrote:

--
Robin Dunn
Software Craftsman

17

moonkid@posteo.org wrote:

I still go on to build the doc (with 'python3 ./build.py dox etg
sphinx). And I don't forget to run 'cleanall'.

There is a problem I don't understand.
The etg command run etg/htmlwin.py. And this py cause a lot of trouble.

The file
"Phoenix/ext/wxWidgets/docs/doxygen/out/xml/wxHtmlLinkEvent"
doesn't exists. Don't know why or if it is needed.

It's telling you that it can't find the XML files containing the definitions of the wxHtmlLinkEvent class. There are actually a few files that it will check for. I'll push a change that prints the list of files that are looked for when none are found, and also raises an exception if none are found.

It may be that you just need to run the dox step again, or if doxygen has changed how they name those files in newer versions then it may need a change to how it builds filenames to look for. If so, the exception will show you where that is. I would have expected it to fail a lot earlier than wxHtmlLinkEvent however if that was the case.

I modified the code, so that the script goes on and just put out a
message about it.

Then htmlwin.py call a lot of ClassDef.find(). And of course it find
nothing. And find() raises exceptions.

So what should be done?

There is one class missing (don't know why) and the complete build
script crash against the wall. I think this behavior is to much.
There could be warnings or errors and then the script should go on.

What do you think?

There are too many cases where if something is missing or broken that many other things will be broken too, so I think that failing is the right thing to do. You wouldn't expect a programming language to just ignore syntax errors and continue on as if that code wasn't present.

···

--
Robin Dunn
Software Craftsman

18

moonkid@posteo.org wrote:

The file
"Phoenix/ext/wxWidgets/docs/doxygen/out/xml/wxHtmlLinkEvent"
doesn't exists. Don't know why or if it is needed.

Maybe this depends on my newer doxygen version (1.8.6)?
I can not test this because the version you are using is not available
at 32bit linux.

It looks like the Doxygen people only build for 64-bit linux. Check in the package repositories for your linux distro, and also for older versions of the distro. It is usually possible to install older versions of packages.

And I don't want to build a external tool just to test a maybe-problem.

It is probably a pretty simple build.

···

On 2015-02-28 03:02<moonkid@posteo.org> wrote:

--
Robin Dunn
Software Craftsman

19

> It is the first time I heard of etg command in the case of producing
> docu.

Really? That's not even the first time I mentioned it in this
thread.

This isn't what I meant. Sorry for my bad english.
I asked about building the doc and somebody gave me the commands for
that. etg wasn't under them. Anyway...

The docs for the modules in the wx.lib, wx.py and wx.tools packages.
Isn't that kinda obvious?

No it isn't.
wxPhoenix is (just) a wrapper for wxWidgets. So of course when I build
the docs the wxWidgets stuff should be involved. Without wxWidgets
there would be no doc. So I even don't understand why there are extra
wx-commands.
So when I build the doc without the wx-commands, what is then there?

You see my point of view?

Especially since the build.py help says:

I know what it says. And your READEM.rst, too and I really stepped into
the build.py code, too.
But please keep in mind that you are the dev who created the
build-process. You know it. But for a foreigner it is really hard to
step into it.
And a plain text big README-file doesn't help with it. Because the
informations in it are kind of unstructured (no hypertext, no table of
content, unconcrete subjects, ...). The build process is nowhere
concrete and detailed described. Except in your mail now...
This informations you gave me here can not be found in the docu.
And code (even nice readable Python code) isn't docu.

     c.addCppMethod('PyObject*', 'Get', '()', """\
         return sipBuildResult(0, "(ii)", self->x, self->y);
         """,
         pyArgsString="() -> (x,y)",
         briefDoc="Return the x and y properties as a tuple.")

Nice. But I even can not see where the description of the return type
come from.
But this doesn't matter anymore. Because someone fixed it. In the
current docu is the return value and type of Point.Get() and Size.Get()
well described. Thats what I wanted.
But I couldn't find the commit for that to see what causes the changes.
etg/gdicmn.h itself is around one year old.

Please keep in mind how important wxPython is. It is unhealthy for each
open source project if only one person can understand and handle the
build process.
Please don't keep this personal! This isn't my goal.
My goal is a successfull and long living wxPython project.

···

On 2015-02-27 21:23 Robin Dunn <robin@alldunn.com> wrote:

moonkid@posteo.org wrote: