Commits

Maciej Fijalkowski committed 41bbdce Merge

attack the docs

Comments (0)

Files changed (10)

 
     http://pypy.org/
 
-The getting-started document will help guide you:
+If you want to help developing PyPy, this document might help you:
 
-    http://doc.pypy.org/en/latest/getting-started.html
+    http://doc.pypy.org/
 
 It will also point you to the rest of the documentation which is generated
 from files in the pypy/doc directory within the source repositories. Enjoy

pypy/doc/dir-reference.rst

+PyPy directory cross-reference 
+------------------------------
+
+Here is a fully referenced alphabetical two-level deep 
+directory overview of PyPy: 
+
+=================================  ============================================
+Directory                          explanation/links
+=================================  ============================================
+`pypy/bin/`_                       command-line scripts, mainly
+                                   `pypy/bin/pyinteractive.py`_
+
+`pypy/config/`_                    handles the numerous options for building
+                                   and running PyPy
+
+`pypy/doc/`_                       text versions of PyPy developer
+                                   documentation
+
+`pypy/doc/config/`_                documentation for the numerous translation
+                                   options
+
+`pypy/doc/discussion/`_            drafts of ideas and documentation
+
+``doc/*/``                         other specific documentation topics or tools
+
+`pypy/interpreter/`_               `bytecode interpreter`_ and related objects
+                                   (frames, functions, modules,...) 
+
+`pypy/interpreter/pyparser/`_      interpreter-level Python source parser
+
+`pypy/interpreter/astcompiler/`_   interpreter-level bytecode compiler,
+                                   via an AST representation
+
+`pypy/module/`_                    contains `mixed modules`_
+                                   implementing core modules with 
+                                   both application and interpreter level code.
+                                   Not all are finished and working.  Use
+                                   the ``--withmod-xxx``
+                                   or ``--allworkingmodules`` translation
+                                   options.
+
+`pypy/objspace/`_                  `object space`_ implementations
+
+`pypy/objspace/std/`_              the StdObjSpace_ implementing CPython's
+                                   objects and types
+
+`pypy/tool/`_                      various utilities and hacks used
+                                   from various places 
+
+`pypy/tool/algo/`_                 general-purpose algorithmic and mathematic
+                                   tools
+
+`pypy/tool/pytest/`_               support code for our `testing methods`_
+
+
+`rpython/annotator/`_              `type inferencing code`_ for
+                                   `RPython`_ programs 
+
+`rpython/config/`_                 handles the numerous options for RPython
+
+
+`rpython/flowspace/`_              the FlowObjSpace_ implementing
+                                   `abstract interpretation`_
+
+`rpython/rlib/`_                   a `"standard library"`_ for RPython_
+                                   programs
+
+`rpython/rtyper/`_                 the `RPython Typer`_ 
+
+`rpython/rtyper/lltypesystem/`_    the `low-level type system`_ for
+                                   C-like backends
+
+`rpython/rtyper/ootypesystem/`_    the `object-oriented type system`_
+                                   for OO backends
+
+`rpython/memory/`_                 the `garbage collector`_ construction
+                                   framework
+
+`rpython/translator/`_             translation_ backends and support code
+
+`rpython/translator/backendopt/`_  general optimizations that run before a 
+                                   backend generates code
+
+`rpython/translator/c/`_           the `GenC backend`_, producing C code
+                                   from an
+                                   RPython program (generally via the rtyper_)
+
+`rpython/translator/cli/`_         the `CLI backend`_ for `.NET`_
+                                   (Microsoft CLR or Mono_)
+
+`pypy/goal/`_                      our `main PyPy-translation scripts`_
+                                   live here
+
+`rpython/translator/jvm/`_         the Java backend
+
+`rpython/translator/tool/`_        helper tools for translation
+
+`dotviewer/`_                      `graph viewer`_
+
+``*/test/``                        many directories have a test subdirectory
+                                   containing test 
+                                   modules (see `Testing in PyPy`_) 
+
+``_cache/``                        holds cache files from various purposes
+=================================  ============================================
+
+.. _`bytecode interpreter`: interpreter.html
+.. _`Testing in PyPy`: coding-guide.html#testing-in-pypy 
+.. _`mixed modules`: coding-guide.html#mixed-modules 
+.. _`modules`: coding-guide.html#modules 
+.. _`basil`: http://people.cs.uchicago.edu/~jriehl/BasilTalk.pdf
+.. _`object space`: objspace.html
+.. _FlowObjSpace: objspace.html#the-flow-object-space 
+.. _`transparent proxies`: objspace-proxies.html#tproxy
+.. _`Differences between PyPy and CPython`: cpython_differences.html
+.. _`What PyPy can do for your objects`: objspace-proxies.html
+.. _`Continulets and greenlets`: stackless.html
+.. _StdObjSpace: objspace.html#the-standard-object-space 
+.. _`abstract interpretation`: http://en.wikipedia.org/wiki/Abstract_interpretation
+.. _`rpython`: coding-guide.html#rpython 
+.. _`type inferencing code`: translation.html#the-annotation-pass 
+.. _`RPython Typer`: translation.html#rpython-typer 
+.. _`testing methods`: coding-guide.html#testing-in-pypy
+.. _`translation`: translation.html 
+.. _`GenC backend`: translation.html#genc 
+.. _`CLI backend`: cli-backend.html
+.. _`py.py`: getting-started-python.html#the-py.py-interpreter
+.. _`translatorshell.py`: getting-started-dev.html#try-out-the-translator
+.. _JIT: jit/index.html
+.. _`JIT Generation in PyPy`: jit/index.html
+.. _`just-in-time compiler generator`: jit/index.html
+.. _rtyper: rtyper.html
+.. _`low-level type system`: rtyper.html#low-level-type
+.. _`object-oriented type system`: rtyper.html#oo-type
+.. _`garbage collector`: garbage_collection.html
+.. _`main PyPy-translation scripts`: getting-started-python.html#translating-the-pypy-python-interpreter
+.. _`.NET`: http://www.microsoft.com/net/
+.. _Mono: http://www.mono-project.com/
+.. _`"standard library"`: rlib.html
+.. _`graph viewer`: getting-started-dev.html#try-out-the-translator

pypy/doc/getting-started-dev.rst

-===============================================================================
-Getting Started with the Translation Toolchain and Development Process
-===============================================================================
+============================
+Getting Started with RPython
+============================
 
 .. contents::
 
+RPython is a subset of Python that can be statically compiled. The PyPy
+interpreter is written mostly in RPython (with pieces in Python), while
+the RPython compiler is written in Python. The hard to understand part
+is that Python is a meta-programming language for RPython, that is,
+RPython is considered from live objects **after** the imports are done.
+This might require more explanation. You start writing RPython from
+``entry_point``, a good starting point is
+``rpython/translator/goal/targetnopstandalone.py``. This does not do all that
+much, but is a start. Now if code analyzed (in this case ``entry_point``)
+calls some functions, those calls will be followed. Those followed calls
+have to be RPython themselves (and everything they call etc.), however not
+entire module files. To show how you can use metaprogramming, we can do
+a silly example (note that closures are not RPython)::
+
+  def generator(operation):
+      if operation == 'add':
+         def f(a, b):
+             return a + b
+      else:
+         def f(a, b):
+             return a - b
+      return f
+
+  add = generator('add')
+  sub = generator('sub')
+
+  def entry_point(argv):
+      print add(sub(int(argv[1]), 3) 4)
+      return 0
+
+In this example ``entry_point`` is RPython,  ``add`` and ``sub`` are RPython,
+however, ``generator`` is not.
+
+A good introductory level articles are available:
+
+* Laurence Tratt -- `Fast Enough VMs in Fast Enough Time`_.
+
+* `How to write interpreters in RPython`_ and `part 2`_ by Andrew Brown.
+
+.. _`Fast Enough VMs in Fast Enough Time`: http://tratt.net/laurie/tech_articles/articles/fast_enough_vms_in_fast_enough_time
+
+.. _`How to write interpreters in RPython`: http://morepypy.blogspot.com/2011/04/tutorial-writing-interpreter-with-pypy.html
+
+.. _`part 2`: http://morepypy.blogspot.com/2011/04/tutorial-part-2-adding-jit.html
+
 .. _`try out the translator`:
 
 Trying out the translator
-------------------------- 
+-------------------------
 
 The translator is a tool based on the PyPy interpreter which can translate
 sufficiently static RPython programs into low-level code (in particular it can
 
     >>> t = Translation(snippet.is_perfect_number, [int])
     >>> t.view()
-        
+
 After that, the graph viewer pops up, that lets you interactively inspect the
 flow graph. To move around, click on something that you want to inspect.
 To get help about how to use it, press 'H'. To close it again, press 'Q'.
 The object returned by ``compile_cli`` or ``compile_jvm``
 is a wrapper around the real
 executable: the parameters are passed as command line arguments, and
-the returned value is read from the standard output.  
+the returned value is read from the standard output.
 
 Once you have compiled the snippet, you can also try to launch the
-executable directly from the shell. You will find the 
+executable directly from the shell. You will find the
 executable in one of the ``/tmp/usession-*`` directories::
 
     # For CLI:

pypy/doc/getting-started-python.rst

 
 
 PyPy's Python interpreter is a very compliant Python
-interpreter implemented in Python.  When translated to C, it passes most of 
+interpreter implemented in RPython.  When compiled, it passes most of 
 `CPythons core language regression tests`_ and comes with many of the extension
 modules included in the standard library including ``ctypes``. It can run large
 libraries such as Django_ and Twisted_. There are some small behavioral
 Translating using the CLI backend
 +++++++++++++++++++++++++++++++++
 
+**Note: the CLI backend is no longer maintained**
+
 To create a standalone .NET executable using the `CLI backend`_::
 
     ./translate.py --backend=cli targetpypystandalone.py

pypy/doc/how-to-contribute.rst

+How to contribute to PyPy
+-------------------------
+
+This page describes how to contribute to the PyPy project. The first thing
+to remember is that PyPy project is very different than most projects out there.
+It's also different from a classic compiler project, so academic courses
+about compilers often don't apply or lead in the wrong direction.
+
+Don't just hack
+---------------
+
+The first and most important rule how not to contribute to PyPy is
+"just hacking". This won't work. There are two major reasons why not
+-- build times are large and PyPy has very thick layer separation which
+make it harder to "just hack a feature".
+
+Test driven development
+-----------------------
+
+Instead, we practice a lot of test driven development. This is partly because
+of very high quality requirements for compilers and partly because there is
+simply no other way to get around such complex project, that will keep you sane.
+There are probably people out there who are smart enough not to need it, we're
+not one of those. You may consider familiarizing yourself with `pytest`_,
+since this is a tool we use for tests.
+This leads to the next issue:
+
+Layers
+------
+
+PyPy has layers. Those layers help us keep the respective parts separated enough
+to be worked on independently and make the complexity manageable. This is,
+again, just a sanity requirement for such a complex project. For example writing
+a new optimization for the JIT usually does **not** involve touching a Python
+interpreter at all or the JIT assembler backend or the garbage collector.
+Instead it requires writing small tests in
+``rpython/jit/metainterp/optimizeopt/test/test_*`` and fixing files there.
+After that, you can just compile PyPy and things should just work.
+
+The short list of layers for further reading. For each of those layers, a good
+entry point is a test subdirectory in respective directories. It usually
+describes (better or worse) the interfaces between the submodules. For the
+``pypy`` subdirectory, most tests are small snippets of python programs that
+check for correctness (calls ``AppTestXxx``) that will call the appropriate
+part of the interpreter. For the ``rpython`` directory, most tests are small
+RPython interpreters that perform certain tasks. To see how they translate
+to low-level graphs, run them with ``--view``. To see small interpreters
+with a JIT compiler, use ``--viewloops`` option.
+
+* **python interpreter** - it's the part implemented in the ``pypy/`` directory.
+  It's implemented in RPython, which is a high level static language with
+  classes, garbage collection, just-in-time compiler generation and the ability
+  to call C. A cool part about it is that it can be run untranslated, so all
+  the tests are runnable without translating PyPy.
+
+  **interpreter** contains the interpreter core
+
+  **objspace** contains implementations of various objects exported to
+  the Python layer
+
+  **module** directory contains extension modules written in RPython
+
+* **rpython compiler** that resides in ``rpython/annotator`` and
+  ``rpython/rtyper`` directories. Consult `introduction to RPython`_ for
+  further reading
+
+* **JIT generator** lives in ``rpython/jit`` directory. optimizations live
+  in ``rpython/jit/metainterp/optimizeopt``, the main JIT in
+  ``rpython/jit/metainterp`` (runtime part) and
+  ``rpython/jit/codewriter`` (translation-time part). Backends live in
+  ``rpython/jit/backend``.
+
+* **garbage collection** lives in ``rpython/memory``
+
+The rest of directories serve specific niche goal and are unlikely a good
+entry point.
+
+.. _`introduction to RPython`: getting-started-dev.rst
 
-Welcome to PyPy Development
-=============================================
+Welcome to PyPy
+===============
 
-The PyPy project aims at producing a flexible and fast Python_
-implementation.  The guiding idea is to translate a Python-level
-description of the Python language itself to lower level languages.
-Rumors have it that the secret goal is being faster-than-C which is
-nonsense, isn't it?  `more...`_
+The PyPy project aims to produce a flexible and fast Python_
+implementation.  This page documents the development of the PyPy
+project itself. If you don't know what PyPy is, consult the `PyPy
+website`_. If you just want to use PyPy, consult the `download`_ page
+and the `getting started with pypy`_ documents. If you want to help
+develop PyPy -- keep reading!
 
-Getting into PyPy ... 
-=============================================
+PyPy is written in a language called `RPython`_, which is suitable for
+writing dynamic language interpreters (and not much else). RPython is
+a subset of Python and is itself written in Python.  If you'd like to
+learn more about RPython, `Starting with RPython`_ should provide a
+reasonable overview.
+
+**If you would like to contribute to PyPy**, please read `how to
+contribute`_ first.  PyPy's development style is somewhat different to
+that of many other software projects and it often surprises
+newcomers. What is **not** necessary is an academic background from
+university in writing compilers -- much of it does not apply to PyPy
+any way.
+
+All of the documentation and source code is available under the MIT license,
+unless otherwise specified. Consult `LICENSE`_
+
+.. _`download`: http://pypy.org/download.html
+.. _`getting started with pypy`: getting-started-python.html
+.. _`RPython`: coding-guide.html#RPython
+.. _`Starting with RPython`: getting-started-dev.html
+.. _`how to contribute`: how-to-contribute.html
+.. _`PyPy website`: http://pypy.org
+
+Index of various topics:
+========================
 
 * `Getting started`_: how to install and run the PyPy Python interpreter
 
 
 * `potential project ideas`_: In case you want to get your feet wet...
 
+* `more stuff`_: this is a collection of documentation that's there, but not
+  particularly organized 
+
 Documentation for the PyPy Python Interpreter
-===============================================
+=============================================
 
 New features of PyPy's Python Interpreter and 
 Translation Framework: 
 
   * `Differences between PyPy and CPython`_
-  * `What PyPy can do for your objects`_
-  * `Continulets and greenlets`_
+  * `What PyPy can do for your objects`_ - transparent proxy documentation
+  * `Continulets and greenlets`_ - documentation about stackless features
   * `JIT Generation in PyPy`_ 
+  * `JIT hooks`_
   * `Sandboxing Python code`_
+  * `Garbage collection environment variables`_
 
 Status_ of the project.
 
+.. _`Differences between PyPy and CPython`: cpython_differences.html
+.. _`What PyPy can do for your objects`: objspace-proxies.html
+.. _`Continulets and greenlets_`: stackless.html
+.. _`JIT Generation in PyPy`: jit/index.html
+.. _`JIT hooks`: jit-hooks.html
+.. _`Sandboxing Python code`: sandbox.html
+.. _`Garbage collection environment variables`: gc_info.html
 
 Mailing lists, bug tracker, IRC channel
 =============================================
 .. _`speed.pypy.org`: http://speed.pypy.org
 .. _`RPython toolchain`: translation.html
 .. _`potential project ideas`: project-ideas.html
-
-Project Documentation
-=====================================
-
-PyPy was funded by the EU for several years. See the `web site of the EU
-project`_ for more details.
-
-.. _`web site of the EU project`: http://pypy.org
-
-architecture_ gives a complete view of PyPy's basic design. 
-
-`coding guide`_ helps you to write code for PyPy (especially also describes
-coding in RPython a bit). 
-
-`sprint reports`_ lists reports written at most of our sprints, from
-2003 to the present.
-
-`papers, talks and related projects`_ lists presentations 
-and related projects as well as our published papers.
-
-`PyPy video documentation`_ is a page linking to the videos (e.g. of talks and
-introductions) that are available.
-
-`Technical reports`_ is a page that contains links to the
-reports that we submitted to the European Union.
-
-`development methodology`_ describes our sprint-driven approach.
-
-`LICENSE`_ contains licensing details (basically a straight MIT-license). 
-
-`Glossary`_ of PyPy words to help you align your inner self with
-the PyPy universe.
-
-
-Status
-===================================
-
-PyPy can be used to run Python programs on Linux, OS/X,
-Windows, on top of .NET, and on top of Java.
-To dig into PyPy it is recommended to try out the current
-Mercurial default branch, which is always working or mostly working,
-instead of the latest release, which is `2.0 beta1`__.
-
-.. __: release-2.0.0-beta1.html
-
-PyPy is mainly developed on Linux and Mac OS X.  Windows is supported,
-but platform-specific bugs tend to take longer before we notice and fix
-them.  Linux 64-bit machines are supported (though it may also take some
-time before we notice and fix bugs).
-
-PyPy's own tests `summary`_, daily updated, run through BuildBot infrastructure.
-You can also find CPython's compliance tests run with compiled ``pypy-c``
-executables there.
-
-
-Source Code Documentation
-===============================================
-
-`object spaces`_ discusses the object space interface 
-and several implementations. 
-
-`bytecode interpreter`_ explains the basic mechanisms 
-of the bytecode interpreter and virtual machine. 
-
-`interpreter optimizations`_ describes our various strategies for
-improving the performance of our interpreter, including alternative
-object implementations (for strings, dictionaries and lists) in the
-standard object space.
-
-`translation`_ is a detailed overview of our translation process.  The
-rtyper_ is the largest component of our translation process.
-
-`dynamic-language translation`_ is a paper that describes
-the translation process, especially the flow object space
-and the annotator in detail. (This document is one
-of the `EU reports`_.)
-
-`low-level encapsulation`_ describes how our approach hides
-away a lot of low level details. This document is also part
-of the `EU reports`_.
-
-`translation aspects`_ describes how we weave different
-properties into our interpreter during the translation
-process. This document is also part of the `EU reports`_.
-
-`garbage collector`_ strategies that can be used by the virtual
-machines produced by the translation process.
-
-`parser`_ contains (outdated, unfinished) documentation about
-the parser.
-
-`rlib`_ describes some modules that can be used when implementing programs in
-RPython.
-
-`configuration documentation`_ describes the various configuration options that
-allow you to customize PyPy.
-
-`CLI backend`_ describes the details of the .NET backend.
-
-`JIT Generation in PyPy`_ describes how we produce the Python Just-in-time Compiler
-from our Python interpreter.
-
-
-
-.. _`FAQ`: faq.html
-.. _Glossary: glossary.html
-.. _`PyPy video documentation`: video-index.html
-.. _parser: parser.html
-.. _`development methodology`: dev_method.html
-.. _`sprint reports`: sprint-reports.html
-.. _`papers, talks and related projects`: extradoc.html
-.. _`object spaces`: objspace.html 
-.. _`interpreter optimizations`: interpreter-optimizations.html 
-.. _`translation`: translation.html 
-.. _`dynamic-language translation`: https://bitbucket.org/pypy/extradoc/raw/tip/eu-report/D05.1_Publish_on_translating_a_very-high-level_description.pdf
-.. _`low-level encapsulation`: low-level-encapsulation.html
-.. _`translation aspects`: translation-aspects.html
-.. _`configuration documentation`: config/
-.. _`coding guide`: coding-guide.html 
-.. _`architecture`: architecture.html 
-.. _`getting started`: getting-started.html 
-.. _`bytecode interpreter`: interpreter.html 
-.. _`EU reports`: index-report.html
-.. _`Technical reports`: index-report.html
-.. _`summary`: http://buildbot.pypy.org/summary
-.. _`ideas for PyPy related projects`: project-ideas.html
-.. _`Nightly builds and benchmarks`: http://tuatara.cs.uni-duesseldorf.de/benchmark.html
-.. _`directory reference`: 
-.. _`rlib`: rlib.html
-.. _`Sandboxing Python code`: sandbox.html
-.. _`LICENSE`: https://bitbucket.org/pypy/pypy/src/default/LICENSE
-
-PyPy directory cross-reference 
-------------------------------
-
-Here is a fully referenced alphabetical two-level deep 
-directory overview of PyPy: 
-
-=================================  ============================================
-Directory                          explanation/links
-=================================  ============================================
-`pypy/bin/`_                       command-line scripts, mainly
-                                   `pypy/bin/pyinteractive.py`_
-
-`pypy/config/`_                    handles the numerous options for building
-                                   and running PyPy
-
-`pypy/doc/`_                       text versions of PyPy developer
-                                   documentation
-
-`pypy/doc/config/`_                documentation for the numerous translation
-                                   options
-
-`pypy/doc/discussion/`_            drafts of ideas and documentation
-
-``doc/*/``                         other specific documentation topics or tools
-
-`pypy/interpreter/`_               `bytecode interpreter`_ and related objects
-                                   (frames, functions, modules,...) 
-
-`pypy/interpreter/pyparser/`_      interpreter-level Python source parser
-
-`pypy/interpreter/astcompiler/`_   interpreter-level bytecode compiler,
-                                   via an AST representation
-
-`pypy/module/`_                    contains `mixed modules`_
-                                   implementing core modules with 
-                                   both application and interpreter level code.
-                                   Not all are finished and working.  Use
-                                   the ``--withmod-xxx``
-                                   or ``--allworkingmodules`` translation
-                                   options.
-
-`pypy/objspace/`_                  `object space`_ implementations
-
-`pypy/objspace/std/`_              the StdObjSpace_ implementing CPython's
-                                   objects and types
-
-`pypy/tool/`_                      various utilities and hacks used
-                                   from various places 
-
-`pypy/tool/algo/`_                 general-purpose algorithmic and mathematic
-                                   tools
-
-`pypy/tool/pytest/`_               support code for our `testing methods`_
-
-
-`rpython/annotator/`_              `type inferencing code`_ for
-                                   `RPython`_ programs 
-
-`rpython/config/`_                 handles the numerous options for RPython
-
-
-`rpython/flowspace/`_              the FlowObjSpace_ implementing
-                                   `abstract interpretation`_
-
-`rpython/rlib/`_                   a `"standard library"`_ for RPython_
-                                   programs
-
-`rpython/rtyper/`_                 the `RPython Typer`_ 
-
-`rpython/rtyper/lltypesystem/`_    the `low-level type system`_ for
-                                   C-like backends
-
-`rpython/rtyper/ootypesystem/`_    the `object-oriented type system`_
-                                   for OO backends
-
-`rpython/memory/`_                 the `garbage collector`_ construction
-                                   framework
-
-`rpython/translator/`_             translation_ backends and support code
-
-`rpython/translator/backendopt/`_  general optimizations that run before a 
-                                   backend generates code
-
-`rpython/translator/c/`_           the `GenC backend`_, producing C code
-                                   from an
-                                   RPython program (generally via the rtyper_)
-
-`rpython/translator/cli/`_         the `CLI backend`_ for `.NET`_
-                                   (Microsoft CLR or Mono_)
-
-`pypy/goal/`_                      our `main PyPy-translation scripts`_
-                                   live here
-
-`rpython/translator/jvm/`_         the Java backend
-
-`rpython/translator/tool/`_        helper tools for translation
-
-`dotviewer/`_                      `graph viewer`_
-
-``*/test/``                        many directories have a test subdirectory
-                                   containing test 
-                                   modules (see `Testing in PyPy`_) 
-
-``_cache/``                        holds cache files from various purposes
-=================================  ============================================
-
-.. _`bytecode interpreter`: interpreter.html
-.. _`Testing in PyPy`: coding-guide.html#testing-in-pypy 
-.. _`mixed modules`: coding-guide.html#mixed-modules 
-.. _`modules`: coding-guide.html#modules 
-.. _`basil`: http://people.cs.uchicago.edu/~jriehl/BasilTalk.pdf
-.. _`object space`: objspace.html
-.. _FlowObjSpace: objspace.html#the-flow-object-space 
-.. _`transparent proxies`: objspace-proxies.html#tproxy
-.. _`Differences between PyPy and CPython`: cpython_differences.html
-.. _`What PyPy can do for your objects`: objspace-proxies.html
-.. _`Continulets and greenlets`: stackless.html
-.. _StdObjSpace: objspace.html#the-standard-object-space 
-.. _`abstract interpretation`: http://en.wikipedia.org/wiki/Abstract_interpretation
-.. _`rpython`: coding-guide.html#rpython 
-.. _`type inferencing code`: translation.html#the-annotation-pass 
-.. _`RPython Typer`: translation.html#rpython-typer 
-.. _`testing methods`: coding-guide.html#testing-in-pypy
-.. _`translation`: translation.html 
-.. _`GenC backend`: translation.html#genc 
-.. _`CLI backend`: cli-backend.html
-.. _`py.py`: getting-started-python.html#the-py.py-interpreter
-.. _`translatorshell.py`: getting-started-dev.html#try-out-the-translator
-.. _JIT: jit/index.html
-.. _`JIT Generation in PyPy`: jit/index.html
-.. _`just-in-time compiler generator`: jit/index.html
-.. _rtyper: rtyper.html
-.. _`low-level type system`: rtyper.html#low-level-type
-.. _`object-oriented type system`: rtyper.html#oo-type
-.. _`garbage collector`: garbage_collection.html
-.. _`main PyPy-translation scripts`: getting-started-python.html#translating-the-pypy-python-interpreter
-.. _`.NET`: http://www.microsoft.com/net/
-.. _Mono: http://www.mono-project.com/
-.. _`"standard library"`: rlib.html
-.. _`graph viewer`: getting-started-dev.html#try-out-the-translator
-
-
-.. The following documentation is important and reasonably up-to-date:
-
-.. extradoc: should this be integrated one level up: dcolish?
-
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   getting-started.rst
-   getting-started-python.rst
-   getting-started-dev.rst
-   windows.rst
-   faq.rst
-   commandline_ref.rst
-   architecture.rst
-   coding-guide.rst
-   cpython_differences.rst
-   garbage_collection.rst
-   gc_info.rst
-   interpreter.rst
-   objspace.rst
-   __pypy__-module.rst
-   objspace-proxies.rst
-   config/index.rst
-
-   dev_method.rst
-   extending.rst
-
-   extradoc.rst
-   video-index.rst
-
-   glossary.rst
-
-   contributor.rst
-
-   interpreter-optimizations.rst
-   configuration.rst
-   parser.rst
-   rlib.rst
-   rtyper.rst
-   rffi.rst
-   
-   translation.rst
-   jit/index.rst
-   jit/overview.rst
-   jit/pyjitpl5.rst
-
-   index-of-release-notes.rst
-
-   ctypes-implementation.rst
-
-   how-to-release.rst
-
-   index-report.rst
-
-   stackless.rst
-   sandbox.rst
-
-   discussions.rst
-
-   cleanup.rst
-
-   sprint-reports.rst
-
-   eventhistory.rst
-   statistic/index.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
-* :ref:`glossary`
-
+.. _`more stuff`: project-documentation.html
 
 .. include:: _ref.txt

pypy/doc/needswork.txt

-.. warning::
-
-   This documentation needs work (as discussed during the Gothenburg sprint in 2011)

pypy/doc/objspace-proxies.rst

 .. contents::
 
 
-
 Thanks to the `Object Space`_ architecture, any feature that is
 based on proxying, extending, changing or otherwise controlling the
 behavior of all objects in a running program is easy to implement on

pypy/doc/project-documentation.rst

+
+Project Documentation
+=====================================
+
+`architecture`_ gives a complete view of PyPy's basic design. 
+
+`coding guide`_ helps you to write code for PyPy (especially also describes
+coding in RPython a bit). 
+
+`sprint reports`_ lists reports written at most of our sprints, from
+2003 to the present.
+
+`papers, talks and related projects`_ lists presentations 
+and related projects as well as our published papers.
+
+`PyPy video documentation`_ is a page linking to the videos (e.g. of talks and
+introductions) that are available.
+
+`Technical reports`_ is a page that contains links to the
+reports that we submitted to the European Union.
+
+`development methodology`_ describes our sprint-driven approach.
+
+`LICENSE`_ contains licensing details (basically a straight MIT-license). 
+
+`Glossary`_ of PyPy words to help you align your inner self with
+the PyPy universe.
+
+Source Code Documentation
+===============================================
+
+`object spaces`_ discusses the object space interface 
+and several implementations. 
+
+`bytecode interpreter`_ explains the basic mechanisms 
+of the bytecode interpreter and virtual machine. 
+
+`interpreter optimizations`_ describes our various strategies for
+improving the performance of our interpreter, including alternative
+object implementations (for strings, dictionaries and lists) in the
+standard object space.
+
+`translation`_ is a detailed overview of our translation process.  The
+rtyper_ is the largest component of our translation process.
+
+`dynamic-language translation`_ is a paper that describes
+the translation process, especially the flow object space
+and the annotator in detail. (This document is one
+of the `EU reports`_.)
+
+`low-level encapsulation`_ describes how our approach hides
+away a lot of low level details. This document is also part
+of the `EU reports`_.
+
+`translation aspects`_ describes how we weave different
+properties into our interpreter during the translation
+process. This document is also part of the `EU reports`_.
+
+`garbage collector`_ strategies that can be used by the virtual
+machines produced by the translation process.
+
+`parser`_ contains (outdated, unfinished) documentation about
+the parser.
+
+`rlib`_ describes some modules that can be used when implementing programs in
+RPython.
+
+`configuration documentation`_ describes the various configuration options that
+allow you to customize PyPy.
+
+`pypy on windows`_
+
+`command line reference`_
+
+`CLI backend`_ describes the details of the .NET backend.
+
+`JIT Generation in PyPy`_ describes how we produce the Python Just-in-time Compiler
+from our Python interpreter.
+
+`directory cross-reference`_
+
+.. _`garbage collector`: garbage_collection.html
+.. _`directory cross-reference`: dir-reference.html
+.. _`pypy on windows`: windows.html
+.. _`command line reference`: commandline_ref.html
+.. _`FAQ`: faq.html
+.. _Glossary: glossary.html
+.. _`PyPy video documentation`: video-index.html
+.. _parser: parser.html
+.. _`development methodology`: dev_method.html
+.. _`sprint reports`: sprint-reports.html
+.. _`papers, talks and related projects`: extradoc.html
+.. _`object spaces`: objspace.html 
+.. _`interpreter optimizations`: interpreter-optimizations.html 
+.. _`translation`: translation.html 
+.. _`dynamic-language translation`: https://bitbucket.org/pypy/extradoc/raw/tip/eu-report/D05.1_Publish_on_translating_a_very-high-level_description.pdf
+.. _`low-level encapsulation`: low-level-encapsulation.html
+.. _`translation aspects`: translation-aspects.html
+.. _`configuration documentation`: config/
+.. _`coding guide`: coding-guide.html 
+.. _`Architecture`: architecture.html 
+.. _`getting started`: getting-started.html 
+.. _`bytecode interpreter`: interpreter.html 
+.. _`EU reports`: index-report.html
+.. _`Technical reports`: index-report.html
+.. _`summary`: http://buildbot.pypy.org/summary
+.. _`ideas for PyPy related projects`: project-ideas.html
+.. _`Nightly builds and benchmarks`: http://tuatara.cs.uni-duesseldorf.de/benchmark.html
+.. _`directory reference`: 
+.. _`rlib`: rlib.html
+.. _`Sandboxing Python code`: sandbox.html
+.. _`LICENSE`: https://bitbucket.org/pypy/pypy/src/default/LICENSE
+
+.. The following documentation is important and reasonably up-to-date:
+
+.. extradoc: should this be integrated one level up: dcolish?
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   interpreter.rst
+   objspace.rst
+   __pypy__-module.rst
+   objspace-proxies.rst
+   config/index.rst
+
+   dev_method.rst
+   extending.rst
+
+   extradoc.rst
+   video-index.rst
+
+   glossary.rst
+
+   contributor.rst
+
+   interpreter-optimizations.rst
+   configuration.rst
+   parser.rst
+   rlib.rst
+   rtyper.rst
+   rffi.rst
+   
+   translation.rst
+   jit/index.rst
+   jit/overview.rst
+   jit/pyjitpl5.rst
+
+   index-of-release-notes.rst
+
+   ctypes-implementation.rst
+
+   how-to-release.rst
+
+   index-report.rst
+
+   stackless.rst
+   sandbox.rst
+
+   discussions.rst
+
+   cleanup.rst
+
+   sprint-reports.rst
+
+   eventhistory.rst
+   statistic/index.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+* :ref:`glossary`
+
+.. include:: _ref.txt

rpython/translator/goal/bpnn.py

         # create weights
         self.wi = makeMatrix(self.ni, self.nh)
         self.wo = makeMatrix(self.nh, self.no)
-        # set them to random vaules
+        # set them to random values
         for i in range(self.ni):
             for j in range(self.nh):
                 self.wi[i][j] = rand(-2.0, 2.0)
         [[1,1], [0]]
     ]
 
-    # create a network with two input, two hidden, and two output nodes
+    # create a network with two input, three hidden, and one output nodes
     n = NN(2, 3, 1)
     # train it with some patterns
     n.train(pat, 2000)