From 5bcffd0b110a60188af43aadbc6aa40250bfb960 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 14 Apr 2004 02:38:44 +0000 Subject: Practical examples of Docutils client code; may be used as-is, or as models for variations. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1928 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docutils/examples.py (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py new file mode 100644 index 000000000..c149bf9d5 --- /dev/null +++ b/docutils/examples.py @@ -0,0 +1,63 @@ +# Authors: David Goodger +# Contact: goodger@python.org +# Revision: $Revision$ +# Date: $Date$ +# Copyright: This module has been placed in the public domain. + +""" +This module contains practical examples of Docutils client code. These +functions may be used as-is, or as models for variations. +""" + +from docutils import core + + +def html_parts(input_string, destination_path=None, + input_encoding='unicode', doctitle=1): + """ + Given an input string, returns a dictionary of HTML document parts. + + Dictionary keys are the names of parts, and values are Unicode strings; + encoding is up to the client. + + Parameters: + + - `input_string`: A multi-line text string; required. + - `destination_path`: Path to the file or object which will receive the + output; optional. Used for determining relative paths (stylesheets, + source links, etc.). + - `input_encoding`: The encoding of `input_string`. If it is an encoded + 8-bit string, provide the correct encoding. If it is a Unicode string, + use "unicode", the default. + - `doctitle`: Disable the promotion of a lone top-level section title to + document title (and subsequent section title to document subtitle + promotion); enabled by default. + """ + overrides = {'input_encoding': input_encoding, + 'doctitle_xform': doctitle} + parts = core.publish_parts( + source=input_string, destination_path=destination_path, + writer_name='html', settings_overrides=overrides) + return parts + +def html_fragment(input_string, destination_path=None, + input_encoding='unicode', output_encoding='unicode', + doctitle=1): + """ + Given an input string, returns an HTML fragment as a string. + + The return value is the contents of the tag, less the title, + subtitle, and docinfo. + + Parameters (see `html_parts()` for the remainder): + + - `output_encoding`: The desired encoding of the output. If a Unicode + string is desired, use the default value of "unicode" . + """ + parts = html_parts( + input_string=input_string, destination_path=destination_path, + input_encoding=input_encoding, doctitle=doctitle) + fragment = parts['fragment'] + if output_endocing != 'unicode': + fragment = fragment.encode(output_encoding) + return fragment -- cgit v1.2.1 From d83957271eed8042a24e0c63974cd3f1a2bbeee1 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 26 Apr 2004 22:09:57 +0000 Subject: fixed typo; found by Stephen Boulet git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1993 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py index c149bf9d5..25c97b293 100644 --- a/docutils/examples.py +++ b/docutils/examples.py @@ -58,6 +58,6 @@ def html_fragment(input_string, destination_path=None, input_string=input_string, destination_path=destination_path, input_encoding=input_encoding, doctitle=doctitle) fragment = parts['fragment'] - if output_endocing != 'unicode': + if output_encoding != 'unicode': fragment = fragment.encode(output_encoding) return fragment -- cgit v1.2.1 From b7ba619ac48b53522d1bbc71c13e35c850c00aa1 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 28 Apr 2004 21:50:39 +0000 Subject: Added support for source_path and initial_header_level. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2011 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py index 25c97b293..bef95ec63 100644 --- a/docutils/examples.py +++ b/docutils/examples.py @@ -12,8 +12,8 @@ functions may be used as-is, or as models for variations. from docutils import core -def html_parts(input_string, destination_path=None, - input_encoding='unicode', doctitle=1): +def html_parts(input_string, source_path=None, destination_path=None, + input_encoding='unicode', doctitle=1, initial_header_level=1): """ Given an input string, returns a dictionary of HTML document parts. @@ -23,6 +23,8 @@ def html_parts(input_string, destination_path=None, Parameters: - `input_string`: A multi-line text string; required. + - `source_path`: Path to the source file or object. Optional, but useful + for diagnostic output (system messages). - `destination_path`: Path to the file or object which will receive the output; optional. Used for determining relative paths (stylesheets, source links, etc.). @@ -32,17 +34,21 @@ def html_parts(input_string, destination_path=None, - `doctitle`: Disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion); enabled by default. + - `initial_header_level`: The initial level for header elements (e.g. 1 + for "

"). """ overrides = {'input_encoding': input_encoding, - 'doctitle_xform': doctitle} + 'doctitle_xform': doctitle, + 'initial_header_level': initial_header_level} parts = core.publish_parts( - source=input_string, destination_path=destination_path, + source=input_string, source_path=source_path, + destination_path=destination_path, writer_name='html', settings_overrides=overrides) return parts -def html_fragment(input_string, destination_path=None, +def html_fragment(input_string, source_path=None, destination_path=None, input_encoding='unicode', output_encoding='unicode', - doctitle=1): + doctitle=1, initial_header_level=1): """ Given an input string, returns an HTML fragment as a string. @@ -55,8 +61,10 @@ def html_fragment(input_string, destination_path=None, string is desired, use the default value of "unicode" . """ parts = html_parts( - input_string=input_string, destination_path=destination_path, - input_encoding=input_encoding, doctitle=doctitle) + input_string=input_string, source_path=source_path, + destination_path=destination_path, + input_encoding=input_encoding, doctitle=doctitle, + initial_header_level=initial_header_level) fragment = parts['fragment'] if output_encoding != 'unicode': fragment = fragment.encode(output_encoding) -- cgit v1.2.1 From a77b2d0f6bad14d3297794bb61bc4e2b85ca0084 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 6 May 2004 16:15:29 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2028 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py index bef95ec63..6936acd25 100644 --- a/docutils/examples.py +++ b/docutils/examples.py @@ -5,8 +5,11 @@ # Copyright: This module has been placed in the public domain. """ -This module contains practical examples of Docutils client code. These -functions may be used as-is, or as models for variations. +This module contains practical examples of Docutils client code. + +Importing this module is not recommended; its contents are subject to change +in future Docutils releases. Instead, it is recommended that you copy and +paste the parts you need into your own code, modifying as necessary. """ from docutils import core -- cgit v1.2.1 From 82cc76e7a4930cfaea13703311d87e6d2e40bbba Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 23 Apr 2005 19:23:57 +0000 Subject: added examples.internals function for exploring git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3247 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py index 6936acd25..3b099b482 100644 --- a/docutils/examples.py +++ b/docutils/examples.py @@ -7,12 +7,13 @@ """ This module contains practical examples of Docutils client code. -Importing this module is not recommended; its contents are subject to change -in future Docutils releases. Instead, it is recommended that you copy and -paste the parts you need into your own code, modifying as necessary. +Importing this module from client code is not recommended; its contents are +subject to change in future Docutils releases. Instead, it is recommended +that you copy and paste the parts you need into your own code, modifying as +necessary. """ -from docutils import core +from docutils import core, io def html_parts(input_string, source_path=None, destination_path=None, @@ -72,3 +73,23 @@ def html_fragment(input_string, source_path=None, destination_path=None, if output_encoding != 'unicode': fragment = fragment.encode(output_encoding) return fragment + +def internals(input_string, source_path=None, destination_path=None, + input_encoding='unicode'): + """ + Return the document tree and publisher, for exploring Docutils internals. + + Parameters: see `html_parts()`. + """ + overrides = {'input_encoding': input_encoding} + output, pub = core.publish_programmatically( + source_class=io.StringInput, source=input_string, + source_path=source_path, + destination_class=io.NullOutput, destination=None, + destination_path=destination_path, + reader=None, reader_name='standalone', + parser=None, parser_name='restructuredtext', + writer=None, writer_name='null', + settings=None, settings_spec=None, settings_overrides=overrides, + config_section=None, enable_exit_status=None) + return pub.writer.document, pub -- cgit v1.2.1 From cbcb754503fce8880ecf7354c82089bde9e4ed22 Mon Sep 17 00:00:00 2001 From: wiemann Date: Mon, 27 Jun 2005 11:19:35 +0000 Subject: changed html_fragment example to the more common html_body git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3598 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/examples.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docutils/examples.py') diff --git a/docutils/examples.py b/docutils/examples.py index 3b099b482..96f6a0522 100644 --- a/docutils/examples.py +++ b/docutils/examples.py @@ -50,14 +50,13 @@ def html_parts(input_string, source_path=None, destination_path=None, writer_name='html', settings_overrides=overrides) return parts -def html_fragment(input_string, source_path=None, destination_path=None, - input_encoding='unicode', output_encoding='unicode', - doctitle=1, initial_header_level=1): +def html_body(input_string, source_path=None, destination_path=None, + input_encoding='unicode', output_encoding='unicode', + doctitle=1, initial_header_level=1): """ Given an input string, returns an HTML fragment as a string. - The return value is the contents of the tag, less the title, - subtitle, and docinfo. + The return value is the contents of the element. Parameters (see `html_parts()` for the remainder): @@ -69,7 +68,7 @@ def html_fragment(input_string, source_path=None, destination_path=None, destination_path=destination_path, input_encoding=input_encoding, doctitle=doctitle, initial_header_level=initial_header_level) - fragment = parts['fragment'] + fragment = parts['html_body'] if output_encoding != 'unicode': fragment = fragment.encode(output_encoding) return fragment -- cgit v1.2.1