Formatter class for text documentation.
| 1215 | return '<%s instance>' % x.__class__.__name__ |
| 1216 | |
| 1217 | class TextDoc(Doc): |
| 1218 | """Formatter class for text documentation.""" |
| 1219 | |
| 1220 | # ------------------------------------------- text formatting utilities |
| 1221 | |
| 1222 | _repr_instance = TextRepr() |
| 1223 | repr = _repr_instance.repr |
| 1224 | |
| 1225 | def bold(self, text): |
| 1226 | """Format a string in bold by overstriking.""" |
| 1227 | return ''.join(ch + '\b' + ch for ch in text) |
| 1228 | |
| 1229 | def indent(self, text, prefix=' '): |
| 1230 | """Indent text by prepending a given prefix to each line.""" |
| 1231 | if not text: return '' |
| 1232 | lines = [prefix + line for line in text.split('\n')] |
| 1233 | if lines: lines[-1] = lines[-1].rstrip() |
| 1234 | return '\n'.join(lines) |
| 1235 | |
| 1236 | def section(self, title, contents): |
| 1237 | """Format a section with a given heading.""" |
| 1238 | clean_contents = self.indent(contents).rstrip() |
| 1239 | return self.bold(title) + '\n' + clean_contents + '\n\n' |
| 1240 | |
| 1241 | # ---------------------------------------------- type-specific routines |
| 1242 | |
| 1243 | def formattree(self, tree, modname, parent=None, prefix=''): |
| 1244 | """Render in text a class tree as returned by inspect.getclasstree().""" |
| 1245 | result = '' |
| 1246 | for entry in tree: |
| 1247 | if type(entry) is type(()): |
| 1248 | c, bases = entry |
| 1249 | result = result + prefix + classname(c, modname) |
| 1250 | if bases and bases != (parent,): |
| 1251 | parents = (classname(c, modname) for c in bases) |
| 1252 | result = result + '(%s)' % ', '.join(parents) |
| 1253 | result = result + '\n' |
| 1254 | elif type(entry) is type([]): |
| 1255 | result = result + self.formattree( |
| 1256 | entry, modname, c, prefix + ' ') |
| 1257 | return result |
| 1258 | |
| 1259 | def docmodule(self, object, name=None, mod=None, *ignored): |
| 1260 | """Produce text documentation for a given module object.""" |
| 1261 | name = object.__name__ # ignore the passed-in name |
| 1262 | synop, desc = splitdoc(getdoc(object)) |
| 1263 | result = self.section('NAME', name + (synop and ' - ' + synop)) |
| 1264 | all = getattr(object, '__all__', None) |
| 1265 | docloc = self.getdocloc(object) |
| 1266 | if docloc is not None: |
| 1267 | result = result + self.section('MODULE REFERENCE', docloc + """ |
| 1268 | |
| 1269 | The following documentation is automatically generated from the Python |
| 1270 | source files. It may be incomplete, incorrect or include features that |
| 1271 | are considered implementation detail and may vary between Python |
| 1272 | implementations. When in doubt, consult the module reference at the |
| 1273 | location listed above. |
| 1274 | """) |