[pypy-commit] pypy improve-docs: Random small fixes (mainly in RPython docs).
Manuel Jacob
noreply at buildbot.pypy.org
Tue May 7 20:23:40 CEST 2013
Author: Manuel Jacob
Branch: improve-docs
Changeset: r63899:f35d5cbbd586
Date: 2013-05-07 12:48 +0200
http://bitbucket.org/pypy/pypy/changeset/f35d5cbbd586/
Log: Random small fixes (mainly in RPython docs).
diff --git a/pypy/doc/getting-started-dev.rst b/pypy/doc/getting-started-dev.rst
--- a/pypy/doc/getting-started-dev.rst
+++ b/pypy/doc/getting-started-dev.rst
@@ -205,22 +205,12 @@
separately announced and often happen around Python conferences such
as EuroPython or Pycon. Upcoming events are usually announced on `the blog`_.
-.. _`full Python interpreter`: getting-started-python.html
.. _`the blog`: http://morepypy.blogspot.com
.. _`pypy-dev mailing list`: http://python.org/mailman/listinfo/pypy-dev
.. _`contact possibilities`: index.html
.. _`py library`: http://pylib.org
-.. _`Spidermonkey`: http://www.mozilla.org/js/spidermonkey/
-
-.. _`.NET Framework SDK`: http://msdn.microsoft.com/netframework/
-.. _Mono: http://www.mono-project.com/Main_Page
-.. _`CLI backend`: cli-backend.html
-.. _clr: clr-module.html
-
-.. _`Dot Graphviz`: http://www.graphviz.org/
-.. _Pygame: http://www.pygame.org/
.. _Standard object space: objspace.html#the-standard-object-space
.. _mailing lists: index.html
.. _documentation: index.html#project-documentation
diff --git a/rpython/doc/cli-backend.rst b/rpython/doc/cli-backend.rst
--- a/rpython/doc/cli-backend.rst
+++ b/rpython/doc/cli-backend.rst
@@ -33,7 +33,7 @@
- the code generation part could be easier because the target
language supports high level control structures such as
structured loops;
-
+
- the generated executables take advantage of compiler's
optimizations.
@@ -59,7 +59,7 @@
generate:
- write IL code to a file, then call the ilasm assembler;
-
+
- directly generate code on the fly by accessing the facilities
exposed by the System.Reflection.Emit API.
@@ -104,14 +104,14 @@
- map ootypesystem's types to CLI Common Type System's
types;
-
+
- map ootypesystem's low level operation to CLI instructions;
-
+
- map Python exceptions to CLI exceptions;
-
+
- write a code generator that translates a flow graph
into a list of CLI instructions;
-
+
- write a class generator that translates ootypesystem
classes into CLI classes.
@@ -137,7 +137,7 @@
one-to-one translation, but has the disadvantage that RPython
strings will not be recognized as .NET strings, since they only
would be sequences of bytes;
-
+
- map both char, so that Python strings will be treated as strings
also by .NET: in this case there could be problems with existing
Python modules that use strings as sequences of byte, such as the
@@ -245,19 +245,19 @@
instruction that raises System.OverflowException when the result
overflows, catch that exception and throw a new one::
- .try
- {
+ .try
+ {
ldarg 'x_0'
ldarg 'y_0'
- add.ovf
+ add.ovf
stloc 'v1'
- leave __check_block_2
- }
- catch [mscorlib]System.OverflowException
- {
- newobj instance void class OverflowError::.ctor()
- throw
- }
+ leave __check_block_2
+ }
+ catch [mscorlib]System.OverflowException
+ {
+ newobj instance void class OverflowError::.ctor()
+ throw
+ }
Translating flow graphs
@@ -308,7 +308,7 @@
...
// IL
- block0:
+ block0:
.try {
...
leave block3
diff --git a/rpython/doc/contents.rst b/rpython/doc/contents.rst
--- a/rpython/doc/contents.rst
+++ b/rpython/doc/contents.rst
@@ -5,7 +5,7 @@
.. toctree::
:maxdepth: 2
-
+
getting-started
faq
rpython
diff --git a/rpython/doc/faq.rst b/rpython/doc/faq.rst
--- a/rpython/doc/faq.rst
+++ b/rpython/doc/faq.rst
@@ -29,16 +29,16 @@
Localized Type Inference of Atomic Types in Python,
http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.90.3231
-.. _`PyPy's RPython`:
+.. _`PyPy's RPython`:
------------------------------
What is this RPython language?
------------------------------
-RPython is a restricted subset of the Python language. It is used for
+RPython is a restricted subset of the Python language. It is used for
implementing dynamic language interpreters within the PyPy toolchain. The
restrictions ensure that type inference (and so, ultimately, translation
-to other languages) of RPython programs is possible.
+to other languages) of RPython programs is possible.
The property of "being RPython" always applies to a full program, not to single
functions or modules (the translation toolchain does a full program analysis).
@@ -64,10 +64,10 @@
Does RPython have anything to do with Zope's Restricted Python?
---------------------------------------------------------------
-No. `Zope's RestrictedPython`_ aims to provide a sandboxed
+No. `Zope's RestrictedPython`_ aims to provide a sandboxed
execution environment for CPython. `PyPy's RPython`_ is the implementation
-language for dynamic language interpreters. However, PyPy also provides
-a robust `sandboxed Python Interpreter`_.
+language for dynamic language interpreters. However, PyPy also provides
+a robust `sandboxed Python Interpreter`_.
.. _`sandboxed Python Interpreter`: sandbox.html
.. _`Zope's RestrictedPython`: http://pypi.python.org/pypi/RestrictedPython
diff --git a/rpython/doc/getting-started.rst b/rpython/doc/getting-started.rst
--- a/rpython/doc/getting-started.rst
+++ b/rpython/doc/getting-started.rst
@@ -11,7 +11,7 @@
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
+:source:`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
@@ -50,6 +50,7 @@
.. _`part 2`: http://morepypy.blogspot.com/2011/04/tutorial-part-2-adding-jit.html
.. _`try out the translator`:
+
Trying out the translator
-------------------------
@@ -61,13 +62,16 @@
* Pygame_
* `Dot Graphviz`_
+.. _Pygame: http://www.pygame.org/
+.. _`Dot Graphviz`: http://www.graphviz.org/
+
To start the interactive translator shell do::
cd rpython
python bin/translatorshell.py
Test snippets of translatable code are provided in the file
-``rpython/translator/test/snippet.py``, which is imported under the name
+:source:`rpython/translator/test/snippet.py`, which is imported under the name
``snippet``. For example::
>>> t = Translation(snippet.is_perfect_number, [int])
@@ -117,7 +121,7 @@
from the interactive translator shells as follows::
>>> def myfunc(a, b): return a+b
- ...
+ ...
>>> t = Translation(myfunc, [int, int])
>>> t.annotate()
>>> f = t.compile_cli() # or compile_jvm()
@@ -143,9 +147,13 @@
To translate and run for the CLI you must have the SDK installed: Windows
users need the `.NET Framework SDK`_, while Linux and Mac users
-can use Mono_. To translate and run for the JVM you must have a JDK
+can use Mono_. To translate and run for the JVM you must have a JDK
installed (at least version 6) and ``java``/``javac`` on your path.
+.. _`CLI backend`: cli-backend.html
+.. _`.NET Framework SDK`: http://msdn.microsoft.com/netframework/
+.. _Mono: http://www.mono-project.com/Main_Page
+
A slightly larger example
+++++++++++++++++++++++++
@@ -169,7 +177,7 @@
+++++++++++++++++++++++++
To translate full RPython programs, there is the script ``translate.py`` in
-``rpython/translator/goal``. Examples for this are a slightly changed version of
+:source:`rpython/translator/goal`. Examples for this are a slightly changed version of
Pystone::
python bin/rpython translator/goal/targetrpystonedalone
@@ -196,23 +204,25 @@
Sources
-------
-* `rpython/translator`_ contains the code analysis and generation stuff.
+* :source:`rpython/translator` contains the code analysis and generation stuff.
Start reading from translator.py, from which it should be easy to follow
the pieces of code involved in the various translation phases.
-* `rpython/annotator`_ contains the data model for the type annotation that
+* :source:`rpython/annotator` contains the data model for the type annotation that
can be inferred about a graph. The graph "walker" that uses this is in
- `rpython/annotator/annrpython.py`_.
+ :source:`rpython/annotator/annrpython.py`.
-* `rpython/rtyper`_ contains the code of the RPython typer. The typer transforms
+* :source:`rpython/rtyper` contains the code of the RPython typer. The typer transforms
annotated flow graphs in a way that makes them very similar to C code so
that they can be easy translated. The graph transformations are controlled
- by the code in `rpython/rtyper/rtyper.py`_. The object model that is used can
- be found in `rpython/rtyper/lltypesystem/lltype.py`_. For each RPython type
+ by the code in :source:`rpython/rtyper/rtyper.py`. The object model that is used can
+ be found in :source:`rpython/rtyper/lltypesystem/lltype.py`. For each RPython type
there is a file rxxxx.py that contains the low level functions needed for
this type.
-* `rpython/rlib`_ contains the `RPython standard library`_, things that you can
+* :source:`rpython/rlib` contains the `RPython standard library`_, things that you can
use from rpython.
+
+.. _`full Python interpreter`: http://pypy.readthedocs.org/en/latest/getting-started-python.html
.. _`RPython standard library`: rlib.html
diff --git a/rpython/doc/rffi.rst b/rpython/doc/rffi.rst
--- a/rpython/doc/rffi.rst
+++ b/rpython/doc/rffi.rst
@@ -1,6 +1,5 @@
-
Foreign Function Interface for RPython
-=======================================
+======================================
Purpose
-------
@@ -47,19 +46,19 @@
Types
-------
+-----
In rffi_ there are various declared types for C-structures, like CCHARP
-(char*), SIZE_T (size_t) and others. refer to file for details.
-Instances of non-primitive types must be alloced by hand, with call
-to lltype.malloc, and freed by lltype.free both with keyword argument
+(char*), SIZE_T (size_t) and others. refer to file for details.
+Instances of non-primitive types must be alloced by hand, with call
+to lltype.malloc, and freed by lltype.free both with keyword argument
flavor='raw'. There are several helpers like string -> char*
converter, refer to the source for details.
.. _rffi: https://bitbucket.org/pypy/pypy/src/tip/pypy/rpython/lltypesystem/rffi.py
Registering function as external
----------------------------------
+--------------------------------
Once we provided low-level implementation of an external function,
would be nice to wrap call to some library function (like os.open)
diff --git a/rpython/doc/rlib.rst b/rpython/doc/rlib.rst
--- a/rpython/doc/rlib.rst
+++ b/rpython/doc/rlib.rst
@@ -1,6 +1,6 @@
-=================================================
-Generally Useful RPython Modules
-=================================================
+================================
+Generally Useful RPython Modules
+================================
.. _Python: http://www.python.org/dev/doc/maint24/ref/ref.html
@@ -158,7 +158,7 @@
parsers in RPython. It is still highly experimental and only really used by the
`Prolog interpreter`_ (although in slightly non-standard ways). The easiest way
to specify a tokenizer/grammar is to write it down using regular expressions and
-simple EBNF format.
+simple EBNF format.
The regular expressions are implemented using finite automatons. The parsing
engine uses `packrat parsing`_, which has O(n) parsing time but is more
@@ -231,7 +231,7 @@
non-significant whitespace.
Grammar rules have the form::
-
+
name: expansion_1 | expansion_2 | ... | expansion_n;
Where ``expansion_i`` is a sequence of nonterminal or token names::
@@ -244,7 +244,7 @@
are strings in quotes that are matched literally.
An example to make this clearer::
-
+
IGNORE: " ";
DECIMAL: "0|[1-9][0-9]*";
additive: multitive "+" additive |
diff --git a/rpython/doc/rpython.rst b/rpython/doc/rpython.rst
--- a/rpython/doc/rpython.rst
+++ b/rpython/doc/rpython.rst
@@ -14,7 +14,7 @@
Flow restrictions
--------------------------
+-----------------
**variables**
@@ -63,7 +63,7 @@
Object restrictions
--------------------------
+-------------------
We are using
@@ -104,12 +104,12 @@
- *indexing*:
positive and negative indexes are allowed. Indexes are checked when requested
by an IndexError exception clause.
-
+
- *slicing*:
the slice start must be within bounds. The stop doesn't need to, but it must
not be smaller than the start. All negative indexes are disallowed, except for
the [:-1] special case. No step. Slice deletion follows the same rules.
-
+
- *slice assignment*:
only supports ``lst[x:y] = sublist``, if ``len(sublist) == y - x``.
In other words, slice assignment cannot change the total length of the list,
@@ -176,7 +176,7 @@
Integer Types
--------------------------
+-------------
While implementing the integer type, we stumbled over the problem that
integers are quite in flux in CPython right now. Starting with Python 2.4,
@@ -229,7 +229,7 @@
Exception rules
----------------------
+---------------
Exceptions are by default not generated for simple cases.::
diff --git a/rpython/doc/rtyper.rst b/rpython/doc/rtyper.rst
--- a/rpython/doc/rtyper.rst
+++ b/rpython/doc/rtyper.rst
@@ -105,7 +105,7 @@
turning representations into explicit objects.
The base Repr class is defined in :source:`rpython/rtyper/rmodel.py`. Most of the
-``rpython/r*.py`` files define one or a few subclasses of Repr. The method
+:source:`rpython/`\ ``r*.py`` files define one or a few subclasses of Repr. The method
getrepr() of the RTyper will build and cache a single Repr instance per
SomeXxx() instance; moreover, two SomeXxx() instances that are equal get the
same Repr instance.
@@ -244,7 +244,7 @@
Structure Types
+++++++++++++++
-Structure types are built as instances of
+Structure types are built as instances of
``rpython.rtyper.lltypesystem.lltype.Struct``::
MyStructType = Struct('somename', ('field1', Type1), ('field2', Type2)...)
@@ -276,7 +276,7 @@
Array Types
+++++++++++
-An array type is built as an instance of
+An array type is built as an instance of
``rpython.rtyper.lltypesystem.lltype.Array``::
MyIntArray = Array(Signed)
@@ -714,7 +714,7 @@
Exception handling:
``hop.has_implicit_exception(cls)``
- Checks if hop is in the scope of a branch catching the exception
+ Checks if hop is in the scope of a branch catching the exception
'cls'. This is useful for high-level operations like 'getitem'
that have several low-level equivalents depending on whether they
should check for an IndexError or not. Calling
diff --git a/rpython/doc/translation.rst b/rpython/doc/translation.rst
--- a/rpython/doc/translation.rst
+++ b/rpython/doc/translation.rst
@@ -106,7 +106,7 @@
.. _`interactive interface`: getting-started-dev.html#try-out-the-translator
.. _`flow model`:
-.. _`control flow graphs`:
+.. _`control flow graphs`:
The Flow Model
==============
@@ -200,7 +200,7 @@
A link from one basic block to another.
:prevblock: the Block that this Link is an exit of.
-
+
:target: the target Block to which this Link points to.
:args: a list of Variables and Constants, of the same size as the
@@ -335,7 +335,7 @@
the same ``SomeXxx`` annotation, and so have all values).
User-defined Classes and Instances
------------------------------------
+----------------------------------
``SomeInstance`` stands for an instance of the given class or any
subclass of it. For each user-defined class seen by the annotator, we
@@ -450,7 +450,7 @@
the "backend optimizations" and the "stackless transform". See also
`D07.1 Massive Parallelism and Translation Aspects`_ for further details.
-.. _`Technical report`:
+.. _`Technical report`:
.. _`D07.1 Massive Parallelism and Translation Aspects`: https://bitbucket.org/pypy/extradoc/raw/ee3059291497/eu-report/D07.1_Massive_Parallelism_and_Translation_Aspects-2007-02-28.pdf
Backend Optimizations
diff --git a/rpython/doc/windows.rst b/rpython/doc/windows.rst
--- a/rpython/doc/windows.rst
+++ b/rpython/doc/windows.rst
@@ -13,12 +13,12 @@
Translating PyPy with Visual Studio
-----------------------------------
-We routinely test the `RPython translation toolchain`_ using
+We routinely test the `RPython translation toolchain`_ using
Visual Studio 2008, Express
Edition. Other configurations may work as well.
The translation scripts will set up the appropriate environment variables
-for the compiler, so you do not need to run vcvars before translation.
+for the compiler, so you do not need to run vcvars before translation.
They will attempt to locate the same compiler version that
was used to build the Python interpreter doing the
translation. Failing that, they will pick the most recent Visual Studio
@@ -65,7 +65,7 @@
Abridged method (for -Ojit builds using Visual Studio 2008)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download the versions of all the external packages
-from
+from
https://bitbucket.org/pypy/pypy/downloads/local.zip
Then expand it into the base directory (base_dir) and modify your environment to reflect this::
@@ -110,15 +110,16 @@
cd bzip2-1.0.5
nmake -f makefile.msc
-
+
The sqlite3 database library
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download http://www.sqlite.org/2013/sqlite-amalgamation-3071601.zip and extract
-it into a directory under the base directory. Also get
+it into a directory under the base directory. Also get
http://www.sqlite.org/2013/sqlite-dll-win32-x86-3071601.zip and extract the dll
into the bin directory, and the sqlite3.def into the sources directory.
Now build the import library so cffi can use the header and dll::
+
lib /DEF:sqlite3.def" /OUT:sqlite3.lib"
copy sqlite3.lib path\to\libs
@@ -128,11 +129,11 @@
Download the source code of expat on sourceforge:
http://sourceforge.net/projects/expat/ and extract it in the base
-directory. Version 2.1.0 is known to pass tests. Then open the project
+directory. Version 2.1.0 is known to pass tests. Then open the project
file ``expat.dsw`` with Visual
Studio; follow the instruction for converting the project files,
-switch to the "Release" configuration, reconfigure the runtime for
-Multi-threaded DLL (/MD) and build the solution (the ``expat`` project
+switch to the "Release" configuration, reconfigure the runtime for
+Multi-threaded DLL (/MD) and build the solution (the ``expat`` project
is actually enough for PyPy).
Then, copy the file ``win32\bin\release\libexpat.dll`` somewhere in
@@ -162,24 +163,24 @@
You probably want to set the CPATH, LIBRARY_PATH, and PATH environment
variables to the header files, lib or dlls, and dlls respectively of the
-locally installed packages if they are not in the mingw directory heirarchy.
+locally installed packages if they are not in the mingw directory heirarchy.
libffi for the mingw compiler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable the _rawffi (and ctypes) module, you need to compile a mingw
version of libffi. Here is one way to do this, wich should allow you to try
to build for win64 or win32:
#. Download and unzip a `mingw32 build`_ or `mingw64 build`_, say into c:\mingw
-#. If you do not use cygwin, you will need msys to provide make,
+#. If you do not use cygwin, you will need msys to provide make,
autoconf tools and other goodies.
#. Download and unzip a `msys for mingw`_, say into c:\msys
#. Edit the c:\msys\etc\fstab file to mount c:\mingw
#. Download and unzip the `libffi source files`_, and extract
- them in the base directory.
+ them in the base directory.
#. Run c:\msys\msys.bat or a cygwin shell which should make you
feel better since it is a shell prompt with shell tools.
#. From inside the shell, cd to the libffi directory and do::
@@ -188,7 +189,7 @@
make
cp .libs/libffi-5.dll <somewhere on the PATH>
-If you can't find the dll, and the libtool issued a warning about
+If you can't find the dll, and the libtool issued a warning about
"undefined symbols not allowed", you will need to edit the libffi
Makefile in the toplevel directory. Add the flag -no-undefined to
the definition of libffi_la_LDFLAGS
@@ -208,6 +209,6 @@
.. _`mingw32 build`: http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Automated%20Builds
.. _`mingw64 build`: http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Automated%20Builds
-.. _`msys for mingw`: http://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/MSYS%20%2832-bit%29
+.. _`msys for mingw`: http://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/MSYS%20%2832-bit%29
.. _`libffi source files`: http://sourceware.org/libffi/
.. _`RPython translation toolchain`: translation.html
More information about the pypy-commit
mailing list