From 765c71b643082e57d8ee7bf38b06f5ba826975a2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 23 May 2010 14:46:52 +0200 Subject: [PATCH 1/3] Deactivate "Binary TOC" option; it seems to prevent the "Locate" button from working correctly. --- sphinx/builders/htmlhelp.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 3ef98f3464..bf486fc93c 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -57,7 +57,7 @@ from sphinx.builders.html import StandaloneHTMLBuilder project_template = '''\ [OPTIONS] -Binary TOC=Yes +Binary TOC=No Binary Index=No Compiled file=%(outname)s.chm Contents file=%(outname)s.hhc From c3c6bba21450a9eb3149320e34b1e1ced08eea3b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 23 May 2010 16:18:30 +0200 Subject: [PATCH 2/3] Fix a problem the Qt help project generated by the ``qthelp`` builder that would lead to no content being displayed in the Qt Assistant. The "namespace" may not contain any non-alphanumeric or non-dot characters, it seems. Also make the help collection file a bit more pretty. --- CHANGES | 4 ++++ sphinx/builders/qthelp.py | 45 +++++++++++++++++++++++++++------------ 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/CHANGES b/CHANGES index 60a496668b..57ec540528 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,10 @@ Release 0.6.6 (in development) ============================== +* Fix a problem the Qt help project generated by the ``qthelp`` + builder that would lead to no content being displayed in the Qt + Assistant. + * #393: Fix the usage of Unicode characters in mathematic formulas when using the ``pngmath`` extension. diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 547bf2fdd1..082c32c3ac 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -13,6 +13,7 @@ import os import re import cgi import codecs +import posixpath from os import path from docutils import nodes @@ -32,6 +33,11 @@ _idpattern = re.compile( collection_template = u'''\ + + %(project)s %(version)s + %(homepage)s + %(startpage)s + @@ -52,9 +58,9 @@ collection_template = u'''\ # actual documentation files (*.html). # In addition it defines a unique namespace for the documentation. project_template = u'''\ - + - %(outname)s.org.%(outname)s.%(nversion)s + %(namespace)s doc %(outname)s @@ -105,17 +111,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): #self.config.html_style = 'traditional.css' def handle_finish(self): - self.build_qhcp(self.outdir, self.config.qthelp_basename) self.build_qhp(self.outdir, self.config.qthelp_basename) - def build_qhcp(self, outdir, outname): - self.info('writing collection project file...') - f = codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8') - try: - f.write(collection_template % {'outname': outname}) - finally: - f.close() - def build_qhp(self, outdir, outname): self.info('writing project file...') @@ -161,16 +158,21 @@ class QtHelpBuilder(StandaloneHTMLBuilder): projectfiles.append(file_template % {'filename': filename}) projectfiles = '\n'.join(projectfiles) + # it seems that the "namespace" may not contain non-alphanumeric + # characters, and more than one successive dot, or leading/trailing + # dots, are also forbidden + nspace = 'org.sphinx.%s.%s' % (outname, self.config.version) + nspace = re.sub('[^a-zA-Z0-9.]', '', nspace) + nspace = re.sub(r'\.+', '.', nspace).strip('.') + # write the project file f = codecs.open(path.join(outdir, outname+'.qhp'), 'w', 'utf-8') try: - nversion = self.config.version.replace('.', '_') - nversion = nversion.replace(' ', '_') f.write(project_template % {'outname': outname, 'title': self.config.html_title, 'version': self.config.version, 'project': self.config.project, - 'nversion': nversion, + 'namespace': nspace, 'masterdoc': self.config.master_doc, 'sections': sections, 'keywords': keywords, @@ -178,6 +180,21 @@ class QtHelpBuilder(StandaloneHTMLBuilder): finally: f.close() + homepage = 'qthelp://' + posixpath.join( + nspace, 'doc', self.get_target_uri(self.config.master_doc)) + startpage = 'qthelp://' + posixpath.join(nspace, 'doc', 'index.html') + + self.info('writing collection project file...') + f = codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8') + try: + f.write(collection_template % {'outname': outname, + 'project': self.config.project, + 'version': self.config.version, + 'homepage': homepage, + 'startpage': startpage}) + finally: + f.close() + def isdocnode(self, node): if not isinstance(node, nodes.list_item): return False From 50058db27358e6e484a4679b7fae9d507c4d4c8e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 23 May 2010 16:22:15 +0200 Subject: [PATCH 3/3] Escape all strings put into the Qt help XML files. --- sphinx/builders/qthelp.py | 43 ++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 082c32c3ac..89bda0dcfc 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -11,10 +11,10 @@ import os import re -import cgi import codecs import posixpath from os import path +from cgi import escape from docutils import nodes @@ -34,7 +34,7 @@ collection_template = u'''\ - %(project)s %(version)s + %(title)s %(homepage)s %(startpage)s @@ -154,8 +154,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): if (resourcedir and not fn.endswith('.js')) or \ fn.endswith('.html'): filename = path.join(root, fn)[olen:] - #filename = filename.replace(os.sep, '\\') # XXX - projectfiles.append(file_template % {'filename': filename}) + projectfiles.append(file_template % + {'filename': escape(filename)}) projectfiles = '\n'.join(projectfiles) # it seems that the "namespace" may not contain non-alphanumeric @@ -168,15 +168,16 @@ class QtHelpBuilder(StandaloneHTMLBuilder): # write the project file f = codecs.open(path.join(outdir, outname+'.qhp'), 'w', 'utf-8') try: - f.write(project_template % {'outname': outname, - 'title': self.config.html_title, - 'version': self.config.version, - 'project': self.config.project, - 'namespace': nspace, - 'masterdoc': self.config.master_doc, - 'sections': sections, - 'keywords': keywords, - 'files': projectfiles}) + f.write(project_template % { + 'outname': escape(outname), + 'title': escape(self.config.html_title), + 'version': escape(self.config.version), + 'project': escape(self.config.project), + 'namespace': escape(nspace), + 'masterdoc': escape(self.config.master_doc), + 'sections': sections, + 'keywords': keywords, + 'files': projectfiles}) finally: f.close() @@ -187,11 +188,11 @@ class QtHelpBuilder(StandaloneHTMLBuilder): self.info('writing collection project file...') f = codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8') try: - f.write(collection_template % {'outname': outname, - 'project': self.config.project, - 'version': self.config.version, - 'homepage': homepage, - 'startpage': startpage}) + f.write(collection_template % { + 'outname': escape(outname), + 'title': escape(self.config.html_short_title), + 'homepage': escape(homepage), + 'startpage': escape(startpage)}) finally: f.close() @@ -213,7 +214,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): if self.isdocnode(node): refnode = node.children[0][0] link = refnode['refuri'] - title = cgi.escape(refnode.astext()).replace('"','"') + title = escape(refnode.astext()).replace('"','"') item = '
' % { 'title': title, 'ref': link} @@ -226,7 +227,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): parts.extend(self.write_toc(subnode, indentlevel)) elif isinstance(node, nodes.reference): link = node['refuri'] - title = cgi.escape(node.astext()).replace('"','"') + title = escape(node.astext()).replace('"','"') item = section_template % {'title': title, 'ref': link} item = ' '*4*indentlevel + item.encode('ascii', 'xmlcharrefreplace') parts.append(item.encode('ascii', 'xmlcharrefreplace')) @@ -263,7 +264,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): def build_keywords(self, title, refs, subitems): keywords = [] - title = cgi.escape(title) + title = escape(title) # if len(refs) == 0: # XXX # write_param('See Also', title) if len(refs) == 1: