1# -*- coding: utf-8 -*- 2 3# Copyright (c) 2017 - 2021 Detlev Offenbach <detlev@die-offenbachs.de> 4# 5 6""" 7Module implementing functions to prepare an HTML documentation view. 8""" 9 10import os 11 12from PyQt5.QtCore import QCoreApplication 13 14from E5Gui.E5Application import e5App 15 16import Utilities 17 18 19_stylesheetsCache = { 20 "dark": "", 21 "light": "", 22} 23 24 25def _stylesheet(): 26 """ 27 Function to get the stylesheet matching the desktop environment. 28 29 @return stylesheet 30 @rtype str 31 """ 32 stylesheetType = "dark" if e5App().usesDarkPalette() else "light" 33 if not _stylesheetsCache[stylesheetType]: 34 # load the stylesheet from file 35 stylesheetFilePath = os.path.join( 36 os.path.dirname(__file__), "data", 37 "documentViewerStyle-{0}.css".format(stylesheetType)) 38 with open(stylesheetFilePath, "r") as f: 39 _stylesheetsCache[stylesheetType] = f.read() 40 41 return _stylesheetsCache[stylesheetType] 42 43 44def prepareDocumentationViewerHtmlDocument(documentationInfo): 45 """ 46 Public function to prepare the HTML document. 47 48 @param documentationInfo dictionary containing the various documentation 49 parts 50 @type dict 51 @return prepared HTML document 52 @rtype str 53 """ 54 mainTemplate = """ 55 <!DOCTYPE html> 56 <html> 57 <head> 58 <meta http-equiv="content-type" content="text/html; charset=utf-8"> 59 <style>{0}</style> 60 </head> 61 <body> 62 @HEADER@ 63 @DOCSTRING@ 64 </body> 65 </html> 66 """ 67 68 headerTemplate = """ 69 @TITLE@ 70 @METADATA@ 71 """ 72 73 titleTemplate = """ 74 <div class="title"><h1>@NAME@</h1></div> 75 """ 76 77 metadataTemplate = """ 78 <div class="metadata"> 79 @ARGSPEC@ 80 @TYPE@ 81 @NOTE@ 82 </div> 83 """ 84 85 argspecTemplate = QCoreApplication.translate( 86 "CodeDocumentationViewer", 87 '<p><b>Definition:</b> <span class="def">@NAME@@ARGSPEC@</span></p>', 88 "Just translate 'Definition:' and leave the rest intact.") 89 90 typeTemplate = QCoreApplication.translate( 91 "CodeDocumentationViewer", 92 "<p><b>Type:</b> @TYPE@</p>", 93 "Just translate 'Type:' and leave the rest intact.") 94 95 noteTemplate = QCoreApplication.translate( 96 "CodeDocumentationViewer", 97 "<p><b>Note:</b> @NOTE@</p>", 98 "Just translate 'Note:' and leave the rest intact.") 99 100 docstringTemplate = """ 101 <div class="docstring"> 102 @DOCSTRING@ 103 </div> 104 """ 105 106 name = documentationInfo["name"] 107 if name: 108 title = titleTemplate.replace("@NAME@", name) 109 if "argspec" in documentationInfo and documentationInfo["argspec"]: 110 argspec = Utilities.html_encode(documentationInfo["argspec"]) 111 for char in ['=', ',', '(', ')', '*', '**']: 112 argspec = argspec.replace( 113 char, 114 '<span class="argspec-highlight">{0}</span>'.format( 115 char)) 116 argspec = ( 117 argspecTemplate 118 .replace("@NAME@", name) 119 .replace("@ARGSPEC@", argspec) 120 ) 121 else: 122 argspec = ( 123 argspecTemplate 124 .replace("@NAME@", name) 125 .replace("@ARGSPEC@", "") 126 ) 127 128 if "typ" in documentationInfo and documentationInfo["typ"]: 129 typeInfo = typeTemplate.replace("@TYPE@", 130 documentationInfo["typ"]) 131 else: 132 typeInfo = "" 133 134 if "note" in documentationInfo and documentationInfo["note"]: 135 note = noteTemplate.replace("@NOTE@", 136 documentationInfo["note"]) 137 else: 138 note = "" 139 140 metaData = ( 141 metadataTemplate 142 .replace("@ARGSPEC@", argspec) 143 .replace("@TYPE@", typeInfo) 144 .replace("@NOTE@", note) 145 ) 146 147 header = ( 148 headerTemplate 149 .replace("@TITLE@", title) 150 .replace("@METADATA@", metaData) 151 ) 152 else: 153 header = "" 154 155 if "docstring" in documentationInfo and documentationInfo["docstring"]: 156 docstring = ( 157 documentationInfo["docstring"] 158 .replace("\r\n", "<br/>") 159 .replace("\n", "<br/>") 160 .replace("\r", "<br/>") 161 ) 162 docstring = docstringTemplate.replace("@DOCSTRING@", docstring) 163 else: 164 docstring = ( 165 """<div class="hr"></div><div id="doc-warning">{0}</div>""" 166 .format(QCoreApplication.translate( 167 "CodeDocumentationViewer", 168 "No further documentation available")) 169 ) 170 171 return ( 172 mainTemplate.format(_stylesheet()) 173 .replace("@HEADER@", header) 174 .replace("@DOCSTRING@", docstring) 175 ) 176 177 178def prepareDocumentationViewerHtmlDocWarningDocument(text): 179 """ 180 Public function to prepare a HTML warning document. 181 182 @param text warning text to be shown 183 @type str 184 @return prepared HTML document 185 @rtype str 186 """ 187 mainTemplate = """ 188 <!DOCTYPE html> 189 <html> 190 <head> 191 <meta http-equiv="content-type" content="text/html; charset=utf-8"> 192 <style>{0}</style> 193 </head> 194 <body> 195 <div id="doc-warning">@TEXT@</div> 196 </body> 197 </html> 198 """ 199 200 return ( 201 mainTemplate.format(_stylesheet()) 202 .replace("@TEXT@", text) 203 ) 204 205 206def prepareDocumentationViewerHtmlWarningDocument(text): 207 """ 208 Public function to prepare a HTML warning document. 209 210 @param text warning text to be shown 211 @type str 212 @return prepared HTML document 213 @rtype str 214 """ 215 mainTemplate = """ 216 <!DOCTYPE html> 217 <html> 218 <head> 219 <meta http-equiv="content-type" content="text/html; charset=utf-8"> 220 <style>{0}</style> 221 </head> 222 <body> 223 <div id="warning">@TEXT@</div> 224 </body> 225 </html> 226 """ 227 228 return ( 229 mainTemplate.format(_stylesheet()) 230 .replace("@TEXT@", text) 231 ) 232