Formatter class for text documentation.
| 1268 | return '<%s instance>' % x.__class__.__name__ |
| 1269 | |
| 1270 | class TextDoc(Doc): |
| 1271 | """Formatter class for text documentation.""" |
| 1272 | |
| 1273 | # ------------------------------------------- text formatting utilities |
| 1274 | |
| 1275 | _repr_instance = TextRepr() |
| 1276 | repr = _repr_instance.repr |
| 1277 | |
| 1278 | def bold(self, text): |
| 1279 | """Format a string in bold by overstriking.""" |
| 1280 | return ''.join(ch + '\b' + ch for ch in text) |
| 1281 | |
| 1282 | def indent(self, text, prefix=' '): |
| 1283 | """Indent text by prepending a given prefix to each line.""" |
| 1284 | if not text: return '' |
| 1285 | lines = [(prefix + line).rstrip() for line in text.split('\n')] |
| 1286 | return '\n'.join(lines) |
| 1287 | |
| 1288 | def section(self, title, contents): |
| 1289 | """Format a section with a given heading.""" |
| 1290 | clean_contents = self.indent(contents).rstrip() |
| 1291 | return self.bold(title) + '\n' + clean_contents + '\n\n' |
| 1292 | |
| 1293 | # ---------------------------------------------- type-specific routines |
| 1294 | |
| 1295 | def formattree(self, tree, modname, parent=None, prefix=''): |
| 1296 | """Render in text a class tree as returned by inspect.getclasstree().""" |
| 1297 | result = '' |
| 1298 | for entry in tree: |
| 1299 | if isinstance(entry, tuple): |
| 1300 | c, bases = entry |
| 1301 | result = result + prefix + classname(c, modname) |
| 1302 | if bases and bases != (parent,): |
| 1303 | parents = (classname(c, modname) for c in bases) |
| 1304 | result = result + '(%s)' % ', '.join(parents) |
| 1305 | result = result + '\n' |
| 1306 | elif isinstance(entry, list): |
| 1307 | result = result + self.formattree( |
| 1308 | entry, modname, c, prefix + ' ') |
| 1309 | return result |
| 1310 | |
| 1311 | def docmodule(self, object, name=None, mod=None, *ignored): |
| 1312 | """Produce text documentation for a given module object.""" |
| 1313 | name = object.__name__ # ignore the passed-in name |
| 1314 | synop, desc = splitdoc(getdoc(object)) |
| 1315 | result = self.section('NAME', name + (synop and ' - ' + synop)) |
| 1316 | all = getattr(object, '__all__', None) |
| 1317 | docloc = self.getdocloc(object) |
| 1318 | if docloc is not None: |
| 1319 | result = result + self.section('MODULE REFERENCE', docloc + """ |
| 1320 | |
| 1321 | The following documentation is automatically generated from the Python |
| 1322 | source files. It may be incomplete, incorrect or include features that |
| 1323 | are considered implementation detail and may vary between Python |
| 1324 | implementations. When in doubt, consult the module reference at the |
| 1325 | location listed above. |
| 1326 | """) |
| 1327 |