Mercurial Repositories > eric / file comparison
comparison: eric6/DocumentationTools/IndexGenerator.py
eric6/DocumentationTools/IndexGenerator.py
- changeset 6942
- 2602857055c5
- parent 6645
- ad476851d7e0
- child 7229
- 53054eb5b15a
equal
deleted
inserted
replaced
| 6941:f99d60d6b59b | 6942:2602857055c5 |
|---|---|
| 1 # -*- coding: utf-8 -*- | |
| 2 | |
| 3 # Copyright (c) 2003 - 2019 Detlev Offenbach <detlev@die-offenbachs.de> | |
| 4 # | |
| 5 | |
| 6 """ | |
| 7 Module implementing the index generator for the builtin documentation | |
| 8 generator. | |
| 9 """ | |
| 10 | |
| 11 from __future__ import unicode_literals | |
| 12 | |
| 13 import sys | |
| 14 import os | |
| 15 | |
| 16 from Utilities import joinext | |
| 17 | |
| 18 | |
| 19 class IndexGenerator(object): | |
| 20 """ | |
| 21 Class implementing the index generator for the builtin documentation | |
| 22 generator. | |
| 23 """ | |
| 24 def __init__(self, outputDir, colors, stylesheet=None): | |
| 25 """ | |
| 26 Constructor | |
| 27 | |
| 28 @param outputDir The output directory for the files. (string) | |
| 29 @param colors Dictionary specifying the various colors for the output. | |
| 30 (dictionary of strings) | |
| 31 @param stylesheet the style to be used for the generated pages (string) | |
| 32 """ | |
| 33 self.outputDir = outputDir | |
| 34 self.packages = { | |
| 35 "00index": { | |
| 36 "description": "", | |
| 37 "subpackages": {}, | |
| 38 "modules": {} | |
| 39 } | |
| 40 } | |
| 41 self.remembered = False | |
| 42 | |
| 43 self.stylesheet = stylesheet | |
| 44 | |
| 45 if self.stylesheet: | |
| 46 from . import TemplatesListsStyleCSS | |
| 47 self.headerTemplate = TemplatesListsStyleCSS.headerTemplate | |
| 48 self.footerTemplate = TemplatesListsStyleCSS.footerTemplate | |
| 49 self.indexBodyTemplate = TemplatesListsStyleCSS.indexBodyTemplate | |
| 50 self.indexListPackagesTemplate = \ | |
| 51 TemplatesListsStyleCSS.indexListPackagesTemplate | |
| 52 self.indexListModulesTemplate = \ | |
| 53 TemplatesListsStyleCSS.indexListModulesTemplate | |
| 54 self.indexListEntryTemplate = \ | |
| 55 TemplatesListsStyleCSS.indexListEntryTemplate | |
| 56 else: | |
| 57 from . import TemplatesListsStyle | |
| 58 self.headerTemplate = \ | |
| 59 TemplatesListsStyle.headerTemplate.format(**colors) | |
| 60 self.footerTemplate = \ | |
| 61 TemplatesListsStyle.footerTemplate.format(**colors) | |
| 62 self.indexBodyTemplate = \ | |
| 63 TemplatesListsStyle.indexBodyTemplate.format(**colors) | |
| 64 self.indexListPackagesTemplate = \ | |
| 65 TemplatesListsStyle.indexListPackagesTemplate.format(**colors) | |
| 66 self.indexListModulesTemplate = \ | |
| 67 TemplatesListsStyle.indexListModulesTemplate.format(**colors) | |
| 68 self.indexListEntryTemplate = \ | |
| 69 TemplatesListsStyle.indexListEntryTemplate.format(**colors) | |
| 70 | |
| 71 def remember(self, file, moduleDocument, basename=""): | |
| 72 """ | |
| 73 Public method to remember a documentation file. | |
| 74 | |
| 75 @param file The filename to be remembered. (string) | |
| 76 @param moduleDocument The ModuleDocument object containing the | |
| 77 information for the file. | |
| 78 @param basename The basename of the file hierarchy to be documented. | |
| 79 The basename is stripped off the filename if it starts with | |
| 80 the basename. | |
| 81 """ | |
| 82 self.remembered = True | |
| 83 if basename: | |
| 84 file = file.replace(basename, "") | |
| 85 | |
| 86 if "__init__" in file: | |
| 87 dirName = os.path.dirname(file) | |
| 88 udir = os.path.dirname(dirName) | |
| 89 if udir: | |
| 90 upackage = udir.replace(os.sep, ".") | |
| 91 try: | |
| 92 elt = self.packages[upackage] | |
| 93 except KeyError: | |
| 94 elt = self.packages["00index"] | |
| 95 else: | |
| 96 elt = self.packages["00index"] | |
| 97 package = dirName.replace(os.sep, ".") | |
| 98 elt["subpackages"][package] = moduleDocument.shortDescription() | |
| 99 | |
| 100 self.packages[package] = { | |
| 101 "description": moduleDocument.description(), | |
| 102 "subpackages": {}, | |
| 103 "modules": {} | |
| 104 } | |
| 105 | |
| 106 if moduleDocument.isEmpty(): | |
| 107 return | |
| 108 | |
| 109 package = os.path.dirname(file).replace(os.sep, ".") | |
| 110 try: | |
| 111 elt = self.packages[package] | |
| 112 except KeyError: | |
| 113 elt = self.packages["00index"] | |
| 114 elt["modules"][moduleDocument.name()] = \ | |
| 115 moduleDocument.shortDescription() | |
| 116 | |
| 117 def __writeIndex(self, packagename, package, newline=None): | |
| 118 """ | |
| 119 Private method to generate an index file for a package. | |
| 120 | |
| 121 @param packagename The name of the package. (string) | |
| 122 @param package A dictionary with information about the package. | |
| 123 @param newline newline character to be used (string) | |
| 124 @return The name of the generated index file. | |
| 125 """ | |
| 126 if packagename == "00index": | |
| 127 f = os.path.join(self.outputDir, "index") | |
| 128 title = "Table of contents" | |
| 129 else: | |
| 130 f = os.path.join(self.outputDir, "index-{0}".format(packagename)) | |
| 131 title = packagename | |
| 132 | |
| 133 filename = joinext(f, ".html") | |
| 134 | |
| 135 subpackages = "" | |
| 136 modules = "" | |
| 137 | |
| 138 # 1) subpackages | |
| 139 if package["subpackages"]: | |
| 140 subpacks = package["subpackages"] | |
| 141 names = sorted(list(subpacks.keys())) | |
| 142 lst = [] | |
| 143 for name in names: | |
| 144 link = joinext("index-{0}".format(name), ".html") | |
| 145 lst.append(self.indexListEntryTemplate.format(**{ | |
| 146 "Description": subpacks[name], | |
| 147 "Name": name.split(".")[-1], | |
| 148 "Link": link, | |
| 149 })) | |
| 150 subpackages = self.indexListPackagesTemplate.format(**{ | |
| 151 "Entries": "".join(lst), | |
| 152 }) | |
| 153 | |
| 154 # 2) modules | |
| 155 if package["modules"]: | |
| 156 mods = package["modules"] | |
| 157 names = sorted(list(mods.keys())) | |
| 158 lst = [] | |
| 159 for name in names: | |
| 160 link = joinext(name, ".html") | |
| 161 nam = name.split(".")[-1] | |
| 162 if nam == "__init__": | |
| 163 nam = name.split(".")[-2] | |
| 164 lst.append(self.indexListEntryTemplate.format(**{ | |
| 165 "Description": mods[name], | |
| 166 "Name": nam, | |
| 167 "Link": link, | |
| 168 })) | |
| 169 modules = self.indexListModulesTemplate.format(**{ | |
| 170 "Entries": "".join(lst), | |
| 171 }) | |
| 172 | |
| 173 doc = self.headerTemplate.format( | |
| 174 **{"Title": title, | |
| 175 "Style": self.stylesheet}) + \ | |
| 176 self.indexBodyTemplate.format( | |
| 177 **{"Title": title, | |
| 178 "Description": package["description"], | |
| 179 "Subpackages": subpackages, | |
| 180 "Modules": modules}) + \ | |
| 181 self.footerTemplate | |
| 182 | |
| 183 f = open(filename, "w", encoding="utf-8", newline=newline) | |
| 184 f.write(doc) | |
| 185 f.close() | |
| 186 | |
| 187 return filename | |
| 188 | |
| 189 def writeIndices(self, basename="", newline=None): | |
| 190 """ | |
| 191 Public method to generate all index files. | |
| 192 | |
| 193 @param basename The basename of the file hierarchy to be documented. | |
| 194 The basename is stripped off the filename if it starts with | |
| 195 the basename. | |
| 196 @param newline newline character to be used (string) | |
| 197 """ | |
| 198 if not self.remembered: | |
| 199 sys.stderr.write("No index to generate.\n") | |
| 200 return | |
| 201 | |
| 202 if basename: | |
| 203 basename = basename.replace(os.sep, ".") | |
| 204 if not basename.endswith("."): | |
| 205 basename = "{0}.".format(basename) | |
| 206 for package, element in list(self.packages.items()): | |
| 207 try: | |
| 208 if basename: | |
| 209 package = package.replace(basename, "") | |
| 210 out = self.__writeIndex(package, element, newline) | |
| 211 except IOError as v: | |
| 212 sys.stderr.write("{0} error: {1}\n".format(package, v[1])) | |
| 213 else: | |
| 214 if out: | |
| 215 sys.stdout.write("{0} ok\n".format(out)) | |
| 216 | |
| 217 sys.stdout.write("Indices written.\n") | |
| 218 sys.stdout.flush() | |
| 219 sys.stderr.flush() |
