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