I am using a wxHtmlHelpController in my application. I currently just
have stub HTML files but it is time for me to write the real help
files. I was thinking that generating the HTML files from a more
general base format such as XML would be the best way to go. I have
looked at tex2rtf (uses TeX files), which produces good results based
on the wxpython TeX files. However, I currently know nothing about
generating TeX files, although I am willing to learn. I played with
Sphinx a bit but the HTMLHelp files generated are not quite up to
standard. The links do not work right and the index is not properly
generated. Of course, I may be doing something wrong but I did use the
Sphinx documentation as a test case so I would have expected that to
produce acceptable results. I have also looked at DocBook and the
htmhelp xslt stylesheet but have yet to get useful results from that.
I am sure that I do not have the XML files quite right. So it looks
like I am going to have to spend some time learning new skills. Before
I embark on that I was wondering what people on this list do for
processing documentation. Maybe there is something I have missed or
maybe I am going down the wrong path.
I am using a wxHtmlHelpController in my application. I currently just
have stub HTML files but it is time for me to write the real help
files. I was thinking that generating the HTML files from a more
general base format such as XML would be the best way to go. I have
looked at tex2rtf (uses TeX files), which produces good results based
on the wxpython TeX files. However, I currently know nothing about
generating TeX files, although I am willing to learn. I played with
Sphinx a bit but the HTMLHelp files generated are not quite up to
standard. The links do not work right and the index is not properly
generated. Of course, I may be doing something wrong but I did use the
Sphinx documentation as a test case so I would have expected that to
produce acceptable results.
I converted over from HelpScribble to Sphinx and generate both html and chm files with it.
What problems did you encounter and did you post your problems on the Sphinx list?
What I did was to enter the Sphinx-0.5.2/doc directory and ran 'sphinx-
build -b htmlhelp . _build'. I then viewed the help files using the
helpviewer program that is distributed with wxpython (helpviewer
_build/htmlhelp/Sphinxdoc.hhp).
The resulting documentation looks wonderful but does not behave as
expected. For instance, from the opening page, select "Documentation",
scroll down a bit and select "reStructuredText Primer|Gotchas". That
link should go to "rest.html#gotchas". But clicking on it goes to the
top of "rest.html", and not to the bottom where the #gotchas tag
should have brought it. The same thing happens with the Contents in
the left pane of the helpviewer window. Clicking on any nested title
will go to the top of the section and not the appropriate part of the
section. I know this is not a problem with the helpviewer app because
the links work as expected with the wxpython documentation generated
with tex2rst and viewed with helpviewer.
The other problem with the Sphinx htmlhelp files is that the index is
not generated properly (I think). Clicking on the "Index" tab in the
left pane of helpviewer shows just one entry although it says there
are three. Either way, there really is no usable index there.
Could it be that the problems are because I am using the HTML files in
the wxHtmlHelpController and not CHM files in a CHM viewer?
Thanks.
···
On Aug 19, 8:29 am, werner <wbru...@free.fr> wrote:
Glenn,
Glenn Johnson wrote:
> I am using a wxHtmlHelpController in my application. I currently just
> have stub HTML files but it is time for me to write the real help
> files. I was thinking that generating the HTML files from a more
> general base format such as XML would be the best way to go. I have
> looked at tex2rtf (uses TeX files), which produces good results based
> on the wxpython TeX files. However, I currently know nothing about
> generating TeX files, although I am willing to learn. I played with
> Sphinx a bit but the HTMLHelp files generated are not quite up to
> standard. The links do not work right and the index is not properly
> generated. Of course, I may be doing something wrong but I did use the
> Sphinx documentation as a test case so I would have expected that to
> produce acceptable results.
I converted over from HelpScribble to Sphinx and generate both html and
chm files with it.
What problems did you encounter and did you post your problems on the
Sphinx list?
The resulting documentation looks wonderful but does not behave as
expected. For instance, from the opening page, select "Documentation",
scroll down a bit and select "reStructuredText Primer|Gotchas". That
link should go to "rest.html#gotchas". But clicking on it goes to the
top of "rest.html", and not to the bottom where the #gotchas tag
should have brought it. The same thing happens with the Contents in
the left pane of the helpviewer window. Clicking on any nested title
will go to the top of the section and not the appropriate part of the
section. I know this is not a problem with the helpviewer app because
the links work as expected with the wxpython documentation generated
with tex2rst and viewed with helpviewer.
The other problem with the Sphinx htmlhelp files is that the index is
not generated properly (I think).
How does it compare with the sample shown in the wx docs? wx's htmlhelp uses a very limited subset of the standard format, so there could be things there that are valid for other tools but which are not understood by htmlhelp.
Clicking on the "Index" tab in the
left pane of helpviewer shows just one entry although it says there
are three. Either way, there really is no usable index there.
Could it be that the problems are because I am using the HTML files in
the wxHtmlHelpController and not CHM files in a CHM viewer?
Yes, it's possible. CHM viewers are typically using a real web browser component, while HtmlHelpController is using a wx.html.HtmlWindow, so it has all the limitations and problems that HtmlWindow does. What version of wx are you using? ISTR that there was a bug concerning named anchor tags a while back, but I think it's been fixed.
On Aug 19, 1:53 pm, Robin Dunn <ro...@alldunn.com> wrote:
Glenn wrote:
> The resulting documentation looks wonderful but does not behave as
> expected. For instance, from the opening page, select "Documentation",
> scroll down a bit and select "reStructuredText Primer|Gotchas". That
> link should go to "rest.html#gotchas". But clicking on it goes to the
> top of "rest.html", and not to the bottom where the #gotchas tag
> should have brought it. The same thing happens with the Contents in
> the left pane of the helpviewer window. Clicking on any nested title
> will go to the top of the section and not the appropriate part of the
> section. I know this is not a problem with the helpviewer app because
> the links work as expected with the wxpython documentation generated
> with tex2rst and viewed with helpviewer.
> The other problem with the Sphinx htmlhelp files is that the index is
> not generated properly (I think).
How does it compare with the sample shown in the wx docs? wx's htmlhelp
uses a very limited subset of the standard format, so there could be
things there that are valid for other tools but which are not understood
by htmlhelp.
> Clicking on the "Index" tab in the
> left pane of helpviewer shows just one entry although it says there
> are three. Either way, there really is no usable index there.
> Could it be that the problems are because I am using the HTML files in
> the wxHtmlHelpController and not CHM files in a CHM viewer?
Yes, it's possible. CHM viewers are typically using a real web browser
component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
has all the limitations and problems that HtmlWindow does. What version
of wx are you using? ISTR that there was a bug concerning named anchor
tags a while back, but I think it's been fixed.
I could see that the contents of the index were actually generated by
looking at the generated hhk file. I downloaded Microsoft's Help
Workbench and could see that the index file was parsed properly in
Help Workbench. I compiled the project into a chm file and read it
with xchm. The index is fine when looking at the chm in xchm. However,
the named anchor tags do not work in xchm, which is perhaps
understandable as it uses wxwidgets. I will take a look at this on my
laptop where I have wx version 2.8.10.1 installed.
···
On Aug 19, 1:53 pm, Robin Dunn <ro...@alldunn.com> wrote:
Glenn wrote:
> The resulting documentation looks wonderful but does not behave as
> expected. For instance, from the opening page, select "Documentation",
> scroll down a bit and select "reStructuredText Primer|Gotchas". That
> link should go to "rest.html#gotchas". But clicking on it goes to the
> top of "rest.html", and not to the bottom where the #gotchas tag
> should have brought it. The same thing happens with the Contents in
> the left pane of the helpviewer window. Clicking on any nested title
> will go to the top of the section and not the appropriate part of the
> section. I know this is not a problem with the helpviewer app because
> the links work as expected with the wxpython documentation generated
> with tex2rst and viewed with helpviewer.
> The other problem with the Sphinx htmlhelp files is that the index is
> not generated properly (I think).
How does it compare with the sample shown in the wx docs? wx's htmlhelp
uses a very limited subset of the standard format, so there could be
things there that are valid for other tools but which are not understood
by htmlhelp.
> Clicking on the "Index" tab in the
> left pane of helpviewer shows just one entry although it says there
> are three. Either way, there really is no usable index there.
> Could it be that the problems are because I am using the HTML files in
> the wxHtmlHelpController and not CHM files in a CHM viewer?
Yes, it's possible. CHM viewers are typically using a real web browser
component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
has all the limitations and problems that HtmlWindow does. What version
of wx are you using? ISTR that there was a bug concerning named anchor
tags a while back, but I think it's been fixed.
With regard to the named anchor tag problem, the tags do work with the
documentation generated with tex2rtf.
···
On Aug 19, 1:53 pm, Robin Dunn <ro...@alldunn.com> wrote:
Glenn wrote:
> The resulting documentation looks wonderful but does not behave as
> expected. For instance, from the opening page, select "Documentation",
> scroll down a bit and select "reStructuredText Primer|Gotchas". That
> link should go to "rest.html#gotchas". But clicking on it goes to the
> top of "rest.html", and not to the bottom where the #gotchas tag
> should have brought it. The same thing happens with the Contents in
> the left pane of the helpviewer window. Clicking on any nested title
> will go to the top of the section and not the appropriate part of the
> section. I know this is not a problem with the helpviewer app because
> the links work as expected with the wxpython documentation generated
> with tex2rst and viewed with helpviewer.
> The other problem with the Sphinx htmlhelp files is that the index is
> not generated properly (I think).
How does it compare with the sample shown in the wx docs? wx's htmlhelp
uses a very limited subset of the standard format, so there could be
things there that are valid for other tools but which are not understood
by htmlhelp.
> Clicking on the "Index" tab in the
> left pane of helpviewer shows just one entry although it says there
> are three. Either way, there really is no usable index there.
> Could it be that the problems are because I am using the HTML files in
> the wxHtmlHelpController and not CHM files in a CHM viewer?
Yes, it's possible. CHM viewers are typically using a real web browser
component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
has all the limitations and problems that HtmlWindow does. What version
of wx are you using? ISTR that there was a bug concerning named anchor
tags a while back, but I think it's been fixed.
Yes, it's possible. CHM viewers are typically using a real web browser
component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
has all the limitations and problems that HtmlWindow does. What version
of wx are you using? ISTR that there was a bug concerning named anchor
tags a while back, but I think it's been fixed.
The wx version is 2.8.9.1.
You may want to try the latest version then and see how good my memory of this is. Otherwise please send us a small standalone example that demonstrates the problem.
Would you say that Sphinx is the way to go?
I'm not very familiar with it myself yet so I can't say, but the current plan is to switch the wxPython docs over when we get far enough into the new approach for generating the wrapper code.
I tried this with the following versions of software:
Python 2.6.2
wxPython 2.8.10.1
wxGTK 2.8.10.1
python-Sphinx 0.6.2
I got the same results, the name anchors do not work and the index tab
of the HtmlHelpController does not work. Note that the HTML index is
fine. I am attaching an htb (zip) archive. Load this into the
helpviewer app that ships with wxPython, click on the index tab in the
left panel. Click on a named anchor, etc.
On Wed, Aug 19, 2009 at 6:09 PM, Robin Dunn<robin@alldunn.com> wrote:
Glenn wrote:
Yes, it's possible. CHM viewers are typically using a real web browser
component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
has all the limitations and problems that HtmlWindow does. What version
of wx are you using? ISTR that there was a bug concerning named anchor
tags a while back, but I think it's been fixed.
The wx version is 2.8.9.1.
You may want to try the latest version then and see how good my memory
of this is. Otherwise please send us a small standalone example that
demonstrates the problem.
I compared the hhk files of the htmlhelp documentation generated from
tex2rtf and sphinx. The following is present just before the start of
the list in the hhk file generated with tex2rtf:
I added that to the hhk file generated from sphinx and that fixes the
index problem.
···
On Aug 19, 5:10 pm, Glenn <glen...@gmail.com> wrote:
On Aug 19, 1:53 pm, Robin Dunn <ro...@alldunn.com> wrote:
> Glenn wrote:
> > The resulting documentation looks wonderful but does not behave as
> > expected. For instance, from the opening page, select "Documentation",
> > scroll down a bit and select "reStructuredText Primer|Gotchas". That
> > link should go to "rest.html#gotchas". But clicking on it goes to the
> > top of "rest.html", and not to the bottom where the #gotchas tag
> > should have brought it. The same thing happens with the Contents in
> > the left pane of the helpviewer window. Clicking on any nested title
> > will go to the top of the section and not the appropriate part of the
> > section. I know this is not a problem with the helpviewer app because
> > the links work as expected with the wxpython documentation generated
> > with tex2rst and viewed with helpviewer.
> > The other problem with the Sphinx htmlhelp files is that the index is
> > not generated properly (I think).
> How does it compare with the sample shown in the wx docs? wx's htmlhelp
> uses a very limited subset of the standard format, so there could be
> things there that are valid for other tools but which are not understood
> by htmlhelp.
> > Clicking on the "Index" tab in the
> > left pane of helpviewer shows just one entry although it says there
> > are three. Either way, there really is no usable index there.
> > Could it be that the problems are because I am using the HTML files in
> > the wxHtmlHelpController and not CHM files in a CHM viewer?
> Yes, it's possible. CHM viewers are typically using a real web browser
> component, while HtmlHelpController is using a wx.html.HtmlWindow, so it
> has all the limitations and problems that HtmlWindow does. What version
> of wx are you using? ISTR that there was a bug concerning named anchor
> tags a while back, but I think it's been fixed.
I could see that the contents of the index were actually generated by
looking at the generated hhk file.
My apologies. I had forgotten that I had run the htmlhelp project file
through MS Help Workbench, which overwrote the index file. So I was
not actually looking at the Sphinx generated hhk file. So it was
actually the file generated by MS Help Workbench that got the index
working in the wxPython HtmlHelpController. I looked at the difference
between the Sphinx hhk file and the MS Help Workbench hhk file. For
the list entries, Sphinx is generating the following HTML:
<param name="Keyword"...>
but MS Help Workbench (and tex2rtf) generate:
<param name="Name"...>
Making that change in the Sphinx generated hhk files is what *really*
gets the index working.
···
On Aug 20, 11:41 am, Glenn <glen...@gmail.com> wrote:
I compared the hhk files of the htmlhelp documentation generated from
tex2rtf and sphinx. The following is present just before the start of
the list in the hhk file generated with tex2rtf:
I tried this with the following versions of software:
Python 2.6.2
wxPython 2.8.10.1
wxGTK 2.8.10.1
python-Sphinx 0.6.2
I got the same results, the name anchors do not work
The Sphinx generated html uses <div>'s for the named anchors, like this: <div class="section" id="prerequisites">. wxHtmlWindow only supports named anchors with <a> tags, like this: <a name="prerequisites">. Try creating a script that scans the files and inserts the <a> tags after those <div>'s.
On Aug 20, 11:41 am, Glenn <glen...@gmail.com> wrote:
I compared the hhk files of the htmlhelp documentation generated from
tex2rtf and sphinx. The following is present just before the start of
the list in the hhk file generated with tex2rtf:
I added that to the hhk file generated from sphinx and that fixes the
index problem.
My apologies. I had forgotten that I had run the htmlhelp project file
through MS Help Workbench, which overwrote the index file. So I was
not actually looking at the Sphinx generated hhk file. So it was
actually the file generated by MS Help Workbench that got the index
working in the wxPython HtmlHelpController. I looked at the difference
between the Sphinx hhk file and the MS Help Workbench hhk file. For
the list entries, Sphinx is generating the following HTML:
<param name="Keyword"...>
but MS Help Workbench (and tex2rtf) generate:
<param name="Name"...>
Making that change in the Sphinx generated hhk files is what *really*
gets the index working.
I think you'll also want to remove the nested lists (the <UL> tags) as wxHtmlHelpController only supports using the single top-level list for the index files.
Great, that will work. Since the documentation for my program will not
be very large, I should be able to work with this.
Thanks.
···
On Aug 20, 2:31 pm, Robin Dunn <ro...@alldunn.com> wrote:
Glenn Johnson wrote:
> I tried this with the following versions of software:
> Python 2.6.2
> wxPython 2.8.10.1
> wxGTK 2.8.10.1
> python-Sphinx 0.6.2
> I got the same results, the name anchors do not work
The Sphinx generated html uses <div>'s for the named anchors, like this:
<div class="section" id="prerequisites">. wxHtmlWindow only supports
named anchors with <a> tags, like this: <a name="prerequisites">. Try
creating a script that scans the files and inserts the <a> tags after
those <div>'s.