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