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

1 files changed, 25 insertions, 4 deletions

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