diff options
Diffstat (limited to 'sphinx/builders/qthelp.py')
| -rw-r--r-- | sphinx/builders/qthelp.py | 137 |
1 files changed, 40 insertions, 97 deletions
diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 0539e18de..44b968111 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -19,6 +19,7 @@ from docutils import nodes from six import text_type from sphinx import addnodes +from sphinx import package_dir from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.config import string_classes from sphinx.environment.adapters.indexentries import IndexEntries @@ -26,6 +27,7 @@ from sphinx.locale import __ from sphinx.util import force_decode, logging from sphinx.util.osutil import make_filename from sphinx.util.pycompat import htmlescape +from sphinx.util.template import SphinxRenderer if False: # For type annotation @@ -40,67 +42,13 @@ _idpattern = re.compile( r'(?P<title>.+) (\((class in )?(?P<id>[\w\.]+)( (?P<descr>\w+))?\))$') -# Qt Help Collection Project (.qhcp). -# Is the input file for the help collection generator. -# It contains references to compressed help files which should be -# included in the collection. -# It may contain various other information for customizing Qt Assistant. -collection_template = u'''\ -<?xml version="1.0" encoding="utf-8" ?> -<QHelpCollectionProject version="1.0"> - <assistant> - <title>%(title)s</title> - <homePage>%(homepage)s</homePage> - <startPage>%(startpage)s</startPage> - </assistant> - <docFiles> - <generate> - <file> - <input>%(outname)s.qhp</input> - <output>%(outname)s.qch</output> - </file> - </generate> - <register> - <file>%(outname)s.qch</file> - </register> - </docFiles> -</QHelpCollectionProject> -''' - -# Qt Help Project (.qhp) -# This is the input file for the help generator. -# It contains the table of contents, indices and references to the -# actual documentation files (*.html). -# In addition it defines a unique namespace for the documentation. -project_template = u'''\ -<?xml version="1.0" encoding="utf-8" ?> -<QtHelpProject version="1.0"> - <namespace>%(namespace)s</namespace> - <virtualFolder>doc</virtualFolder> - <customFilter name="%(project)s %(version)s"> - <filterAttribute>%(outname)s</filterAttribute> - <filterAttribute>%(version)s</filterAttribute> - </customFilter> - <filterSection> - <filterAttribute>%(outname)s</filterAttribute> - <filterAttribute>%(version)s</filterAttribute> - <toc> - <section title="%(title)s" ref="%(masterdoc)s.html"> -%(sections)s - </section> - </toc> - <keywords> -%(keywords)s - </keywords> - <files> -%(files)s - </files> - </filterSection> -</QtHelpProject> -''' - section_template = '<section title="%(title)s" ref="%(ref)s"/>' -file_template = ' ' * 12 + '<file>%(filename)s</file>' + + +def render_file(filename, **kwargs): + # type: (unicode, Any) -> unicode + pathname = os.path.join(package_dir, 'templates', 'qthelp', filename) + return SphinxRenderer.render_from_file(pathname, kwargs) class QtHelpBuilder(StandaloneHTMLBuilder): @@ -184,24 +132,6 @@ class QtHelpBuilder(StandaloneHTMLBuilder): keywords.extend(self.build_keywords(title, refs, subitems)) keywords = u'\n'.join(keywords) # type: ignore - # files - if not outdir.endswith(os.sep): - outdir += os.sep - olen = len(outdir) - projectfiles = [] - staticdir = path.join(outdir, '_static') - imagesdir = path.join(outdir, self.imagedir) - for root, dirs, files in os.walk(outdir): - resourcedir = root.startswith(staticdir) or \ - root.startswith(imagesdir) - for fn in sorted(files): - if (resourcedir and not fn.endswith('.js')) or \ - fn.endswith('.html'): - filename = path.join(root, fn)[olen:] - projectfiles.append(file_template % - {'filename': htmlescape(filename)}) - projectfiles = '\n'.join(projectfiles) # type: ignore - # it seems that the "namespace" may not contain non-alphanumeric # characters, and more than one successive dot, or leading/trailing # dots, are also forbidden @@ -216,16 +146,13 @@ class QtHelpBuilder(StandaloneHTMLBuilder): # write the project file with codecs.open(path.join(outdir, outname + '.qhp'), 'w', 'utf-8') as f: # type: ignore # NOQA - f.write(project_template % { - 'outname': htmlescape(outname), - 'title': htmlescape(self.config.html_title), - 'version': htmlescape(self.config.version), - 'project': htmlescape(self.config.project), - 'namespace': htmlescape(nspace), - 'masterdoc': htmlescape(self.config.master_doc), - 'sections': sections, - 'keywords': keywords, - 'files': projectfiles}) + body = render_file('project.qhp', outname=outname, + title=self.config.html_title, version=self.config.version, + project=self.config.project, namespace=nspace, + master_doc=self.config.master_doc, + sections=sections, keywords=keywords, + files=self.get_project_files(outdir)) + f.write(body) homepage = 'qthelp://' + posixpath.join( nspace, 'doc', self.get_target_uri(self.config.master_doc)) @@ -233,11 +160,10 @@ class QtHelpBuilder(StandaloneHTMLBuilder): logger.info(__('writing collection project file...')) with codecs.open(path.join(outdir, outname + '.qhcp'), 'w', 'utf-8') as f: # type: ignore # NOQA - f.write(collection_template % { - 'outname': htmlescape(outname), - 'title': htmlescape(self.config.html_short_title), - 'homepage': htmlescape(homepage), - 'startpage': htmlescape(startpage)}) + body = render_file('project.qhcp', outname=outname, + title=self.config.html_short_title, + homepage=homepage, startpage=startpage) + f.write(body) def isdocnode(self, node): # type: (nodes.Node) -> bool @@ -299,11 +225,12 @@ class QtHelpBuilder(StandaloneHTMLBuilder): else: id = None + nameattr = htmlescape(name, quote=True) + refattr = htmlescape(ref[1], quote=True) if id: - item = ' ' * 12 + '<keyword name="%s" id="%s" ref="%s"/>' % ( - name, id, ref[1]) + item = ' ' * 12 + '<keyword name="%s" id="%s" ref="%s"/>' % (nameattr, id, refattr) else: - item = ' ' * 12 + '<keyword name="%s" ref="%s"/>' % (name, ref[1]) + item = ' ' * 12 + '<keyword name="%s" ref="%s"/>' % (nameattr, refattr) item.encode('ascii', 'xmlcharrefreplace') return item @@ -311,7 +238,6 @@ class QtHelpBuilder(StandaloneHTMLBuilder): # type: (unicode, List[Any], Any) -> List[unicode] keywords = [] # type: List[unicode] - title = htmlescape(title) # if len(refs) == 0: # XXX # write_param('See Also', title) if len(refs) == 1: @@ -331,6 +257,23 @@ class QtHelpBuilder(StandaloneHTMLBuilder): return keywords + def get_project_files(self, outdir): + # type: (unicode) -> List[unicode] + if not outdir.endswith(os.sep): + outdir += os.sep + olen = len(outdir) + project_files = [] + staticdir = path.join(outdir, '_static') + imagesdir = path.join(outdir, self.imagedir) + for root, dirs, files in os.walk(outdir): + resourcedir = root.startswith((staticdir, imagesdir)) + for fn in sorted(files): + if (resourcedir and not fn.endswith('.js')) or fn.endswith('.html'): + filename = path.join(root, fn)[olen:] + project_files.append(filename) + + return project_files + def setup(app): # type: (Sphinx) -> Dict[unicode, Any] |