zopefoundation · loechel · Mar 3, 2017 · Feb 3, 2017 · Feb 4, 2017 · Feb 4, 2017
diff --git a/README.rst b/README.rst
@@ -0,0 +1,7 @@
+================
+RestrictedPython
+================
+
+RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment.
+
+For full documentation please see  http://restrictedpython.readthedocs.io/en/python3_update/ or local docs/index.
diff --git a/README.txt b/README.txt
diff --git a/CHANGES.rst → docs/CHANGES.rst b/CHANGES.rst → docs/CHANGES.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,8 +29,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
+    'sphinx.ext.doctest',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -117,6 +119,10 @@
 
 }
 
+# Options for sphinx.ext.todo:
+todo_include_todos = True
+todo_emit_warnings = True
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -0,0 +1,11 @@
+Contributing
+============
+
+Contributing to RestrictedPython 4+
+
+
+
+Todos
+-----
+
+.. todolist::
diff --git a/docs/index.rst b/docs/index.rst
@@ -25,6 +25,11 @@ Contents
    upgrade/index
    upgrade_dependencies/index
 
+   roadmap/index
+   contributing/index
+
+   CHANGES
+
 Indices and tables
 ==================
 

diff --git a/docs/install/index.rst b/docs/install/index.rst
@@ -0,0 +1,10 @@
+Install / Depend on RestrictedPython
+====================================
+
+RestrictedPython is usually not used stand alone, if you use it in context of your package add it to ``install_requires`` in your ``setup.py`` or a ``requirement.txt`` used by ``pip``.
+
+For a standalone usage:
+
+.. code:: bash
+
+    pip install RestrictedPython
diff --git a/docs/roadmap/index.rst b/docs/roadmap/index.rst
@@ -0,0 +1,39 @@
+Roadmap for RestrictedPython
+============================
+
+RestrictedPython 4.0
+--------------------
+
+A feature complete rewrite of RestrictedPython using ``ast`` module instead of ``compile`` package.
+RestrictedPython 4.0 should not add any new or remove restrictions.
+
+A detailed documentation that support usage and further development.
+
+Full code coverage tests.
+
+.. todo::
+
+    Complete documentation of all public API elements with docstyle comments
+    https://www.python.org/dev/peps/pep-0257/
+    http://www.sphinx-doc.org/en/stable/ext/autodoc.html
+    http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html
+
+.. todo::
+
+    Resolve Discussion in https://github.com/zopefoundation/RestrictedPython/pull/39#issuecomment-283074699
+
+    compile_restricted optional params flags and dont_inherit will not work as expected with the current implementation.
+
+    stephan-hof did propose a solution, should be discussed and if approved implemented.
+
+
+RestrictedPython 4.1+
+---------------------
+
+Enhance RestrictedPython, declare  deprecations and possible new restrictions.
+
+RestrictedPython 5.0+
+---------------------
+
+* Python 3+ only, no more support for Python 2.7
+* mypy - Static Code Analysis Annotations
diff --git a/docs/update_notes.rst b/docs/update_notes.rst
diff --git a/docs/upgrade/ast/python2_6.ast b/docs/upgrade/ast/python2_6.ast
@@ -81,20 +81,49 @@ module Python version "2.6"
         -- col_offset is the byte offset in the utf8 string the parser uses
         attributes (int lineno, int col_offset)
 
-  expr_context = Load | Store | Del | AugLoad | AugStore | Param
-
-  slice = Ellipsis | Slice(expr? lower, expr? upper, expr? step)
+  expr_context = Load
+               | Store
+               | Del
+               | AugLoad
+               | AugStore
+               | Param
+
+  slice = Ellipsis
+        | Slice(expr? lower, expr? upper, expr? step)
         | ExtSlice(slice* dims)
         | Index(expr value)
 
-  boolop = And | Or
-
-  operator = Add | Sub | Mult | Div | Mod | Pow | LShift
-                 | RShift | BitOr | BitXor | BitAnd | FloorDiv
-
-  unaryop = Invert | Not | UAdd | USub
-
-  cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn
+  boolop = And
+         | Or
+
+  operator = Add
+           | Sub
+           | Mult
+           | Div
+           | Mod
+           | Pow
+           | LShift
+           | RShift
+           | BitOr
+           | BitXor
+           | BitAnd
+           | FloorDiv
+
+  unaryop = Invert
+          | Not
+          | UAdd
+          | USub
+
+  cmpop = Eq
+        | NotEq
+        | Lt
+        | LtE
+        | Gt
+        | GtE
+        | Is
+        | IsNot
+        | In
+        | NotIn
 
   comprehension = (expr target, expr iter, expr* ifs)
 
@@ -103,11 +132,11 @@ module Python version "2.6"
                   attributes (int lineno, int col_offset)
 
   arguments = (expr* args, identifier? vararg,
-         identifier? kwarg, expr* defaults)
+               identifier? kwarg, expr* defaults)
 
-        -- keyword arguments supplied to call
-        keyword = (identifier arg, expr value)
+  -- keyword arguments supplied to call
+  keyword = (identifier arg, expr value)
 
-        -- import name with optional 'as' alias.
-        alias = (identifier name, identifier? asname)
+  -- import name with optional 'as' alias.
+  alias = (identifier name, identifier? asname)
 }
diff --git a/docs/upgrade/ast/python2_7.ast b/docs/upgrade/ast/python2_7.ast
@@ -11,7 +11,7 @@ module Python version "2.7"
       | Suite(stmt* body)
 
   stmt = FunctionDef(identifier name, arguments args,
-                            stmt* body, expr* decorator_list)
+                     stmt* body, expr* decorator_list)
         | ClassDef(identifier name, expr* bases, stmt* body, expr* decorator_list)
         | Return(expr? value)
 
@@ -84,20 +84,48 @@ module Python version "2.7"
         -- col_offset is the byte offset in the utf8 string the parser uses
         attributes (int lineno, int col_offset)
 
-  expr_context = Load | Store | Del | AugLoad | AugStore | Param
+  expr_context = Load
+               | Store
+               | Del
+               | AugLoad
+               | AugStore
+               | Param
 
-  slice = Ellipsis | Slice(expr? lower, expr? upper, expr? step)
+  slice = Ellipsis
+        | Slice(expr? lower, expr? upper, expr? step)
         | ExtSlice(slice* dims)
         | Index(expr value)
 
   boolop = And | Or
 
-  operator = Add | Sub | Mult | Div | Mod | Pow | LShift
-                 | RShift | BitOr | BitXor | BitAnd | FloorDiv
-
-  unaryop = Invert | Not | UAdd | USub
-
-  cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn
+  operator = Add
+           | Sub
+           | Mult
+           | Div
+           | Mod
+           | Pow
+           | LShift
+           | RShift
+           | BitOr
+           | BitXor
+           | BitAnd
+           | FloorDiv
+
+  unaryop = Invert
+          | Not
+          | UAdd
+          | USub
+
+  cmpop = Eq
+        | NotEq
+        | Lt
+        | LtE
+        | Gt
+        | GtE
+        | Is
+        | IsNot
+        | In
+        | NotIn
 
   comprehension = (expr target, expr iter, expr* ifs)
 
@@ -106,11 +134,11 @@ module Python version "2.7"
                   attributes (int lineno, int col_offset)
 
   arguments = (expr* args, identifier? vararg,
-         identifier? kwarg, expr* defaults)
+               identifier? kwarg, expr* defaults)
 
-        -- keyword arguments supplied to call
-        keyword = (identifier arg, expr value)
+  -- keyword arguments supplied to call
+  keyword = (identifier arg, expr value)
 
-        -- import name with optional 'as' alias.
-        alias = (identifier name, identifier? asname)
+  -- import name with optional 'as' alias.
+  alias = (identifier name, identifier? asname)
 }