| Tor Norbye | 3a2425a | 2013-11-04 10:16:08 -0800 | [diff] [blame^] | 1 | # $Id: examples.py 4800 2006-11-12 18:02:01Z goodger $ |
| 2 | # Author: David Goodger <goodger@python.org> |
| 3 | # Copyright: This module has been placed in the public domain. |
| 4 | |
| 5 | """ |
| 6 | This module contains practical examples of Docutils client code. |
| 7 | |
| 8 | Importing this module from client code is not recommended; its contents are |
| 9 | subject to change in future Docutils releases. Instead, it is recommended |
| 10 | that you copy and paste the parts you need into your own code, modifying as |
| 11 | necessary. |
| 12 | """ |
| 13 | |
| 14 | from docutils import core, io |
| 15 | |
| 16 | |
| 17 | def html_parts(input_string, source_path=None, destination_path=None, |
| 18 | input_encoding='unicode', doctitle=1, initial_header_level=1): |
| 19 | """ |
| 20 | Given an input string, returns a dictionary of HTML document parts. |
| 21 | |
| 22 | Dictionary keys are the names of parts, and values are Unicode strings; |
| 23 | encoding is up to the client. |
| 24 | |
| 25 | Parameters: |
| 26 | |
| 27 | - `input_string`: A multi-line text string; required. |
| 28 | - `source_path`: Path to the source file or object. Optional, but useful |
| 29 | for diagnostic output (system messages). |
| 30 | - `destination_path`: Path to the file or object which will receive the |
| 31 | output; optional. Used for determining relative paths (stylesheets, |
| 32 | source links, etc.). |
| 33 | - `input_encoding`: The encoding of `input_string`. If it is an encoded |
| 34 | 8-bit string, provide the correct encoding. If it is a Unicode string, |
| 35 | use "unicode", the default. |
| 36 | - `doctitle`: Disable the promotion of a lone top-level section title to |
| 37 | document title (and subsequent section title to document subtitle |
| 38 | promotion); enabled by default. |
| 39 | - `initial_header_level`: The initial level for header elements (e.g. 1 |
| 40 | for "<h1>"). |
| 41 | """ |
| 42 | overrides = {'input_encoding': input_encoding, |
| 43 | 'doctitle_xform': doctitle, |
| 44 | 'initial_header_level': initial_header_level} |
| 45 | parts = core.publish_parts( |
| 46 | source=input_string, source_path=source_path, |
| 47 | destination_path=destination_path, |
| 48 | writer_name='html', settings_overrides=overrides) |
| 49 | return parts |
| 50 | |
| 51 | def html_body(input_string, source_path=None, destination_path=None, |
| 52 | input_encoding='unicode', output_encoding='unicode', |
| 53 | doctitle=1, initial_header_level=1): |
| 54 | """ |
| 55 | Given an input string, returns an HTML fragment as a string. |
| 56 | |
| 57 | The return value is the contents of the <body> element. |
| 58 | |
| 59 | Parameters (see `html_parts()` for the remainder): |
| 60 | |
| 61 | - `output_encoding`: The desired encoding of the output. If a Unicode |
| 62 | string is desired, use the default value of "unicode" . |
| 63 | """ |
| 64 | parts = html_parts( |
| 65 | input_string=input_string, source_path=source_path, |
| 66 | destination_path=destination_path, |
| 67 | input_encoding=input_encoding, doctitle=doctitle, |
| 68 | initial_header_level=initial_header_level) |
| 69 | fragment = parts['html_body'] |
| 70 | if output_encoding != 'unicode': |
| 71 | fragment = fragment.encode(output_encoding) |
| 72 | return fragment |
| 73 | |
| 74 | def internals(input_string, source_path=None, destination_path=None, |
| 75 | input_encoding='unicode', settings_overrides=None): |
| 76 | """ |
| 77 | Return the document tree and publisher, for exploring Docutils internals. |
| 78 | |
| 79 | Parameters: see `html_parts()`. |
| 80 | """ |
| 81 | if settings_overrides: |
| 82 | overrides = settings_overrides.copy() |
| 83 | else: |
| 84 | overrides = {} |
| 85 | overrides['input_encoding'] = input_encoding |
| 86 | output, pub = core.publish_programmatically( |
| 87 | source_class=io.StringInput, source=input_string, |
| 88 | source_path=source_path, |
| 89 | destination_class=io.NullOutput, destination=None, |
| 90 | destination_path=destination_path, |
| 91 | reader=None, reader_name='standalone', |
| 92 | parser=None, parser_name='restructuredtext', |
| 93 | writer=None, writer_name='null', |
| 94 | settings=None, settings_spec=None, settings_overrides=overrides, |
| 95 | config_section=None, enable_exit_status=None) |
| 96 | return pub.writer.document, pub |