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 |
|