rework doctests in documentation to use .. testcode:: instead of .. d…

…octest::

docs/conf.py

@@ -118,6 +118,10 @@
 
 }
 
+# Options for sphinx.ext.todo:
+todo_include_todos = False
+todo_emit_warnings = True
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/contributing/index.rst

@@ -2,3 +2,10 @@ Contributing
 ============
 
 Contributing to RestrictedPython 4+
+
+
+
+Todos
+-----
+
+.. todolist::

docs/usage/basic_usage.rst

@@ -3,7 +3,7 @@ Basic usage
 
 The general workflow to execute Python code that is loaded within a Python program is:
 
-.. code:: Python
+.. testcode::
 
     source_code = """
     def do_something():
@@ -14,21 +14,9 @@ The general workflow to execute Python code that is loaded within a Python progr
     exec(byte_code)
     do_something()
 
-.. doctest::
-    :hide:
-
-    >>> source_code = """
-    ... def do_something():
-    ...     pass
-    ... """
-    >>> byte_code = compile(source_code, filename='<inline code>', mode='exec')
-    >>> exec(byte_code)
-    >>> do_something()
-
-
 With RestrictedPython that workflow should be as straight forward as possible:
 
-.. code:: Python
+.. testcode:: Python
 
     from RestrictedPython import compile_restricted
 
@@ -41,21 +29,9 @@ With RestrictedPython that workflow should be as straight forward as possible:
     exec(byte_code)
     do_something()
 
-.. doctest::
-    :hide:
-
-    >>> from RestrictedPython import compile_restricted
-    >>> source_code = """
-    ... def do_something():
-    ...     pass
-    ... """
-    >>> byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec')
-    >>> exec(byte_code)
-    >>> do_something()
-
 You might also use the replacement import:
 
-.. code:: Python
+.. testcode:: Python
 
     from RestrictedPython import compile_restricted as compile
 
@@ -87,45 +63,27 @@ RestrictedPython provides three predefined built-ins for that (see :ref:`predefi
 
 So you normally end up using:
 
-.. code:: Python
+.. testcode::
 
-    #from RestrictedPython import ..._builtins
+    from RestrictedPython import compile_restricted
+
+    # from RestrictedPython import ..._builtins
     from RestrictedPython import safe_builtins
     from RestrictedPython import limited_builtins
     from RestrictedPython import utility_builtins
-    from RestrictedPython import compile_restricted
 
-    source_code = """<demo code>"""
+    source_code = """
+    def do_something():
+        pass
+    """
 
     try:
-        byte_code = compile_restricted(source_code, filename='<name>', mode='exec')
+        byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec')
 
-        #used_builtins = ..._builtins + { <additionl elems> } # Whitelisting additional elements
+        # used_builtins = ..._builtins + { <additionl elems> } # Whitelisting additional elements
         used_builtins = safe_builtins
         exec(byte_code, used_builtins, None)
     except SyntaxError as e:
-        ...
-
-.. doctest::
-    :hide:
-
-    >>> #from RestrictedPython import ..._builtins
-    >>> from RestrictedPython import safe_builtins
-    >>> from RestrictedPython import limited_builtins
-    >>> from RestrictedPython import utility_builtins
-    >>> from RestrictedPython import compile_restricted
-
-    >>> source_code = """
-    ... def do_something():
-    ...     pass
-    ... """
-
-    >>> try:
-    ...     byte_code = compile_restricted(source_code, filename='<name>', mode='exec')
-    ...     #used_builtins = ..._builtins + { <additionl elems> } # Whitelisting additional elements
-    ...     used_builtins = safe_builtins
-    ...     exec(byte_code, used_builtins, None)
-    ... except SyntaxError as e:
-    ...     pass
+        pass
 
 One common advanced usage would be to define an own restricted builtin dictionary.

docs/usage/framework_usage.rst

@@ -35,46 +35,39 @@ For that use case RestrictedPython provides the possibility to pass an own polic
 
 A policy is basically a special ``NodeTransformer`` that could be instantiated with three params for ``errors``, ``warnings`` and ``used_names``, it should be a subclass of RestrictedPython.RestrictingNodeTransformer.
 
-.. todo::
+.. testcode:: Python
 
-    write doctests for following code
+    from RestrictedPython import compile_restricted
+    from RestrictedPython import RestrictingNodeTransformer
+    class OwnRestrictingNodeTransformer(RestrictingNodeTransformer):
+        pass
 
-.. code:: Python
-
-    OwnRestrictingNodeTransformer(errors=[], warnings=[], used_names=[])
+    policy = OwnRestrictingNodeTransformer(errors=[], warnings=[], used_names=[])
 
 All ``compile_restricted*`` methods do have a optional parameter ``policy``, where a specific policy could be provided.
 
-.. code:: Python
+.. testcode:: Python
 
-    source_code = """<demo code>"""
+    source_code = """
+    def do_something():
+        pass
+    """
 
     policy = OwnRestrictingNodeTransformer
 
     byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec', policy=policy)
-    exec(byte_code, { ... }, { ... })
+    # exec(byte_code, { ... }, { ... })
+    exec(byte_code, globals(), None)
 
 One special case "unrestricted RestrictedPython" (defined to unblock ports of Zope Packages to Python 3) is to actually use RestrictedPython in an unrestricted mode, by providing a Null-Policy (aka ``None``).
 That special case would be written as:
 
-.. code:: Python
+.. testcode:: Python
 
-    source_code = """<demo code>"""
+    source_code = """
+    def do_something():
+        pass
+    """
 
     byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec', policy=None)
     exec(byte_code, globals(), None)
-
-.. doctest::
-    :hide:
-
-    >>> from RestrictedPython import compile_restricted
-    >>>
-    >>> source_code = """
-    ... def do_something():
-    ...    pass
-    ...
-    ... do_something()
-    ... """
-    >>>
-    >>> byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec', policy=None)
-    >>> exec(byte_code, globals(), None)