[pypy-commit] pypy improve-docs: Kill _ref.txt and fix references.
Manuel Jacob
noreply at buildbot.pypy.org
Mon May 6 17:03:27 CEST 2013
Author: Manuel Jacob
Branch: improve-docs
Changeset: r63888:3d8f4d764dae
Date: 2013-05-06 16:39 +0200
http://bitbucket.org/pypy/pypy/changeset/3d8f4d764dae/
Log: Kill _ref.txt and fix references.
diff --git a/pypy/doc/_ref.txt b/pypy/doc/_ref.txt
deleted file mode 100644
--- a/pypy/doc/_ref.txt
+++ /dev/null
@@ -1,116 +0,0 @@
-.. _`ctypes_configure/doc/sample.py`: https://bitbucket.org/pypy/pypy/src/default/ctypes_configure/doc/sample.py
-.. _`dotviewer/`: https://bitbucket.org/pypy/pypy/src/default/dotviewer/
-.. _`lib-python/`: https://bitbucket.org/pypy/pypy/src/default/lib-python/
-.. _`lib-python/2.7/dis.py`: https://bitbucket.org/pypy/pypy/src/default/lib-python/2.7/dis.py
-.. _`lib_pypy/`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/
-.. _`lib_pypy/greenlet.py`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/greenlet.py
-.. _`lib_pypy/pypy_test/`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/pypy_test/
-.. _`lib_pypy/tputil.py`: https://bitbucket.org/pypy/pypy/src/default/lib_pypy/tputil.py
-.. _`pypy/bin/`: https://bitbucket.org/pypy/pypy/src/default/pypy/bin/
-.. _`pypy/bin/pyinteractive.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/bin/pyinteractive.py
-.. _`pypy/config/`: https://bitbucket.org/pypy/pypy/src/default/pypy/config/
-.. _`pypy/config/pypyoption.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/config/pypyoption.py
-.. _`pypy/doc/`: https://bitbucket.org/pypy/pypy/src/default/pypy/doc/
-.. _`pypy/doc/config/`: https://bitbucket.org/pypy/pypy/src/default/pypy/doc/config/
-.. _`pypy/doc/discussion/`: https://bitbucket.org/pypy/pypy/src/default/pypy/doc/discussion/
-.. _`pypy/goal/`: https://bitbucket.org/pypy/pypy/src/default/pypy/goal/
-.. _`pypy/interpreter`:
-.. _`pypy/interpreter/`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/
-.. _`pypy/interpreter/argument.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/argument.py
-.. _`pypy/interpreter/astcompiler`:
-.. _`pypy/interpreter/astcompiler/`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/
-.. _`pypy/interpreter/astcompiler/assemble.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/assemble.py
-.. _`pypy/interpreter/astcompiler/ast.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/ast.py
-.. _`pypy/interpreter/astcompiler/astbuilder.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/astbuilder.py
-.. _`pypy/interpreter/astcompiler/asthelpers.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/asthelpers.py
-.. _`pypy/interpreter/astcompiler/codegen.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/codegen.py
-.. _`pypy/interpreter/astcompiler/optimize.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/optimize.py
-.. _`pypy/interpreter/astcompiler/symtable.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/symtable.py
-.. _`pypy/interpreter/astcompiler/tools/Python.asdl`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/tools/Python.asdl
-.. _`pypy/interpreter/astcompiler/tools/asdl_py.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/astcompiler/tools/asdl_py.py
-.. _`pypy/interpreter/baseobjspace.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/baseobjspace.py
-.. _`pypy/interpreter/eval.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/eval.py
-.. _`pypy/interpreter/executioncontext.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/executioncontext.py
-.. _`pypy/interpreter/function.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/function.py
-.. _`pypy/interpreter/gateway.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/gateway.py
-.. _`pypy/interpreter/mixedmodule.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/mixedmodule.py
-.. _`pypy/interpreter/module.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/module.py
-.. _`pypy/interpreter/nestedscope.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/nestedscope.py
-.. _`pypy/interpreter/pyframe.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyframe.py
-.. _`pypy/interpreter/pyopcode.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyopcode.py
-.. _`pypy/interpreter/pyparser`:
-.. _`pypy/interpreter/pyparser/`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/
-.. _`pypy/interpreter/pyparser/future.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/future.py
-.. _`pypy/interpreter/pyparser/metaparser.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/metaparser.py
-.. _`pypy/interpreter/pyparser/parser.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/parser.py
-.. _`pypy/interpreter/pyparser/pyparse.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/pyparse.py
-.. _`pypy/interpreter/pyparser/pytokenizer.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/pyparser/pytokenizer.py
-.. _`pypy/interpreter/typedef.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/interpreter/typedef.py
-.. _`pypy/module`:
-.. _`pypy/module/`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/
-.. _`pypy/module/__builtin__/__init__.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/module/__builtin__/__init__.py
-.. _`pypy/objspace/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/
-.. _`pypy/objspace/flow/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/flow/
-.. _`pypy/objspace/std`:
-.. _`pypy/objspace/std/`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/
-.. _`pypy/objspace/std/listtype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/listtype.py
-.. _`pypy/objspace/std/multimethod.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/multimethod.py
-.. _`pypy/objspace/std/objspace.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/objspace.py
-.. _`pypy/objspace/std/proxy_helpers.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/proxy_helpers.py
-.. _`pypy/objspace/std/proxyobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/proxyobject.py
-.. _`pypy/objspace/std/stringtype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/stringtype.py
-.. _`pypy/objspace/std/transparent.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/transparent.py
-.. _`pypy/objspace/std/tupleobject.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/tupleobject.py
-.. _`pypy/objspace/std/tupletype.py`: https://bitbucket.org/pypy/pypy/src/default/pypy/objspace/std/tupletype.py
-.. _`pypy/tool/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/
-.. _`pypy/tool/algo/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/algo/
-.. _`pypy/tool/pytest/`: https://bitbucket.org/pypy/pypy/src/default/pypy/tool/pytest/
-.. _`rpython/annotator`:
-.. _`rpython/annotator/`: https://bitbucket.org/pypy/pypy/src/default/rpython/annotator/
-.. _`rpython/annotator/annrpython.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/annotator/annrpython.py
-.. _`rpython/annotator/binaryop.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/annotator/binaryop.py
-.. _`rpython/annotator/builtin.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/annotator/builtin.py
-.. _`rpython/bin/translatorshell.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/bin/translatorshell.py
-.. _`rpython/config/`: https://bitbucket.org/pypy/pypy/src/default/rpython/config/
-.. _`rpython/config/translationoption.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/config/translationoption.py
-.. _`rpython/flowspace/`: https://bitbucket.org/pypy/pypy/src/default/rpython/flowspace/
-.. _`rpython/flowspace/model.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/flowspace/model.py
-.. _`rpython/rlib`:
-.. _`rpython/rlib/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/
-.. _`rpython/rlib/listsort.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/listsort.py
-.. _`rpython/rlib/nonconst.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/nonconst.py
-.. _`rpython/rlib/objectmodel.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/objectmodel.py
-.. _`rpython/rlib/parsing/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/parsing/
-.. _`rpython/rlib/parsing/tree.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/parsing/tree.py
-.. _`rpython/rlib/rarithmetic.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/rarithmetic.py
-.. _`rpython/rlib/rbigint.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/rbigint.py
-.. _`rpython/rlib/rrandom.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/rrandom.py
-.. _`rpython/rlib/rsocket.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/rsocket.py
-.. _`rpython/rlib/streamio.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/streamio.py
-.. _`rpython/rlib/test`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/test/
-.. _`rpython/rlib/unroll.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rlib/unroll.py
-.. _`rpython/rtyper`:
-.. _`rpython/rtyper/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/
-.. _`rpython/rtyper/lltypesystem/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/lltypesystem/
-.. _`rpython/rtyper/lltypesystem/lltype.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/lltypesystem/lltype.py
-.. _`rpython/rtyper/memory/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/
-.. _`rpython/rtyper/memory/gc/generation.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/generation.py
-.. _`rpython/rtyper/memory/gc/hybrid.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/hybrid.py
-.. _`rpython/rtyper/memory/gc/minimarkpage.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/minimarkpage.py
-.. _`rpython/rtyper/memory/gc/semispace.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/memory/gc/semispace.py
-.. _`rpython/rtyper/ootypesystem/`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/ootypesystem/
-.. _`rpython/rtyper/ootypesystem/ootype.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/ootypesystem/ootype.py
-.. _`rpython/rtyper/rint.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rint.py
-.. _`rpython/rtyper/rlist.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rlist.py
-.. _`rpython/rtyper/rmodel.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rmodel.py
-.. _`rpython/rtyper/rtyper.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/rtyper.py
-.. _`rpython/rtyper/test/test_llinterp.py`: https://bitbucket.org/pypy/pypy/src/default/rpython/rtyper/test/test_llinterp.py
-.. _`rpython/translator`:
-.. _`rpython/translator/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/
-.. _`rpython/translator/backendopt/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/backendopt/
-.. _`rpython/translator/c/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/c/
-.. _`rpython/translator/c/src/stacklet/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/c/src/stacklet/
-.. _`rpython/translator/c/src/stacklet/stacklet.h`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/c/src/stacklet/stacklet.h
-.. _`rpython/translator/cli/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/cli/
-.. _`rpython/translator/jvm/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/jvm/
-.. _`rpython/translator/tool/`: https://bitbucket.org/pypy/pypy/src/default/rpython/translator/tool/
diff --git a/pypy/doc/architecture.rst b/pypy/doc/architecture.rst
--- a/pypy/doc/architecture.rst
+++ b/pypy/doc/architecture.rst
@@ -258,6 +258,3 @@
.. _`generate Just-In-Time Compilers`: jit/index.html
.. _`JIT Generation in PyPy`: jit/index.html
.. _`implement your own interpreter`: http://morepypy.blogspot.com/2011/04/tutorial-writing-interpreter-with-pypy.html
-
-.. include:: _ref.txt
-
diff --git a/pypy/doc/coding-guide.rst b/pypy/doc/coding-guide.rst
--- a/pypy/doc/coding-guide.rst
+++ b/pypy/doc/coding-guide.rst
@@ -159,7 +159,7 @@
elegant: For the definition of all the opcodes of the Python
interpreter, the module ``dis`` is imported and used to initialize our
bytecode interpreter. (See ``__initclass__`` in
-`pypy/interpreter/pyopcode.py`_). This
+:source:`pypy/interpreter/pyopcode.py`). This
saves us from adding extra modules to PyPy. The import code is run at
startup time, and we are allowed to use the CPython builtin import
function.
@@ -304,11 +304,11 @@
because they rely on implementation details of CPython.
If we don't just modify an original CPython module but need to rewrite
-it from scratch we put it into `lib_pypy/`_ as a pure application level
+it from scratch we put it into :source:`lib_pypy/` as a pure application level
module.
When we need access to interpreter-level objects we put the module into
-`pypy/module`_. Such modules use a `mixed module mechanism`_
+:source:`pypy/module`. Such modules use a `mixed module mechanism`_
which makes it convenient to use both interpreter- and application-level parts
for the implementation. Note that there is no extra facility for
pure-interpreter level modules, you just write a mixed module and leave the
@@ -381,7 +381,7 @@
If a module needs to access PyPy's interpreter level
then it is implemented as a mixed module.
-Mixed modules are directories in `pypy/module`_ with an `__init__.py`
+Mixed modules are directories in :source:`pypy/module` with an `__init__.py`
file containing specifications where each name in a module comes from.
Only specified names will be exported to a Mixed Module's applevel
namespace.
@@ -399,7 +399,7 @@
Application level specifications are found in the `appleveldefs`
dictionary found in ``__init__.py`` files of directories in ``pypy/module``.
-For example, in `pypy/module/__builtin__/__init__.py`_ you find the following
+For example, in :source:`pypy/module/__builtin__/__init__.py` you find the following
entry specifying where ``__builtin__.locals`` comes from::
...
@@ -415,7 +415,7 @@
Interpreter level specifications are found in the ``interpleveldefs``
dictionary found in ``__init__.py`` files of directories in ``pypy/module``.
-For example, in `pypy/module/__builtin__/__init__.py`_ the following
+For example, in :source:`pypy/module/__builtin__/__init__.py` the following
entry specifies where ``__builtin__.len`` comes from::
...
@@ -453,11 +453,11 @@
Testing modules in ``lib_pypy/``
--------------------------------
-You can go to the `lib_pypy/pypy_test/`_ directory and invoke the testing tool
+You can go to the :source:`lib_pypy/pypy_test/` directory and invoke the testing tool
("py.test" or "python ../../pypy/test_all.py") to run tests against the
-lib_pypy hierarchy. Note, that tests in `lib_pypy/pypy_test/`_ are allowed
+lib_pypy hierarchy. Note, that tests in :source:`lib_pypy/pypy_test/` are allowed
and encouraged to let their tests run at interpreter level although
-`lib_pypy/`_ modules eventually live at PyPy's application level.
+:source:`lib_pypy/` modules eventually live at PyPy's application level.
This allows us to quickly test our python-coded reimplementations
against CPython.
@@ -472,7 +472,7 @@
-----------------------------------
In order to let CPython's regression tests run against PyPy
-you can switch to the `lib-python/`_ directory and run
+you can switch to the :source:`lib-python/` directory and run
the testing tool in order to start compliance tests.
(XXX check windows compatibility for producing test reports).
@@ -710,6 +710,3 @@
make linkcheck
which will check that remote URLs are reachable.
-
-
-.. include:: _ref.txt
diff --git a/pypy/doc/configuration.rst b/pypy/doc/configuration.rst
--- a/pypy/doc/configuration.rst
+++ b/pypy/doc/configuration.rst
@@ -188,8 +188,6 @@
toolchain`_
toolchain, have two separate sets of options. The translation toolchain options
can be found on the ``config`` attribute of all ``TranslationContext``
-instances and are described in `rpython/config/translationoption.py`_. The interpreter options
+instances and are described in :source:`rpython/config/translationoption.py`. The interpreter options
are attached to the object space, also under the name ``config`` and are
-described in `pypy/config/pypyoption.py`_.
-
-.. include:: _ref.txt
+described in :source:`pypy/config/pypyoption.py`.
diff --git a/pypy/doc/cpython_differences.rst b/pypy/doc/cpython_differences.rst
--- a/pypy/doc/cpython_differences.rst
+++ b/pypy/doc/cpython_differences.rst
@@ -16,7 +16,7 @@
List of extension modules that we support:
-* Supported as built-in modules (in `pypy/module/`_):
+* Supported as built-in modules (in :source:`pypy/module/`):
__builtin__
`__pypy__`_
@@ -77,7 +77,7 @@
zlib
When translated to Java or .NET, the list is smaller; see
- `pypy/config/pypyoption.py`_ for details.
+ :source:`pypy/config/pypyoption.py` for details.
When translated on Windows, a few Unix-only modules are skipped,
and the following module is built instead:
@@ -85,14 +85,14 @@
_winreg
* Supported by being rewritten in pure Python (possibly using ``ctypes``):
- see the `lib_pypy/`_ directory. Examples of modules that we
+ see the :source:`lib_pypy/` directory. Examples of modules that we
support this way: ``ctypes``, ``cPickle``, ``cmath``, ``dbm``, ``datetime``...
Note that some modules are both in there and in the list above;
by default, the built-in module is used (but can be disabled
at translation time).
The extension modules (i.e. modules written in C, in the standard CPython)
-that are neither mentioned above nor in `lib_pypy/`_ are not available in PyPy.
+that are neither mentioned above nor in :source:`lib_pypy/` are not available in PyPy.
(You may have a chance to use them anyway with `cpyext`_.)
.. the nonstandard modules are listed below...
@@ -316,6 +316,3 @@
opposed to a dict proxy like in CPython. Mutating the dict will change the
type and vice versa. For builtin types, a dictionary will be returned that
cannot be changed (but still looks and behaves like a normal dictionary).
-
-
-.. include:: _ref.txt
diff --git a/pypy/doc/ctypes-implementation.rst b/pypy/doc/ctypes-implementation.rst
--- a/pypy/doc/ctypes-implementation.rst
+++ b/pypy/doc/ctypes-implementation.rst
@@ -1,6 +1,6 @@
-=============================
-PyPy's ctypes implementation
-=============================
+============================
+PyPy's ctypes implementation
+============================
Summary
========
@@ -33,12 +33,12 @@
Low-level part: ``_rawffi``
============================
-This PyPy extension module (``pypy/module/_rawffi``) exposes a simple interface
+This PyPy extension module (:source:`pypy/module/_rawffi`) exposes a simple interface
to create C objects (arrays and structures) and calling functions
in dynamic libraries through libffi. Freeing objects in most cases and making
sure that objects referring to each other are kept alive is responsibility of the higher levels.
-This module uses bindings to libffi which are defined in ``rpython/rlib/libffi.py``.
+This module uses bindings to libffi which are defined in :source:`rpython/rlib/libffi.py`.
We tried to keep this module as small as possible. It is conceivable
that other implementations (e.g. Jython) could use our ctypes
@@ -101,7 +101,7 @@
We tried pyglet checking it out from its repository at revision 1984.
From pyglet, the following examples are known to work:
-
+
- opengl.py
- multiple_windows.py
- events.py
@@ -157,7 +157,4 @@
usage
-----
-`ctypes_configure/doc/sample.py`_ explains in details how to use it.
-
-
-.. include:: _ref.txt
+:source:`ctypes_configure/doc/sample.py` explains in details how to use it.
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
@@ -14,24 +14,24 @@
relative to the PyPy top level directory). You may look at our `directory reference`_
or start off at one of the following points:
-* `pypy/interpreter`_ contains the bytecode interpreter: bytecode dispatcher
- in `pypy/interpreter/pyopcode.py`_, frame and code objects in `pypy/interpreter/eval.py`_ and `pypy/interpreter/pyframe.py`_,
- function objects and argument passing in `pypy/interpreter/function.py`_ and `pypy/interpreter/argument.py`_,
- the object space interface definition in `pypy/interpreter/baseobjspace.py`_, modules in
- `pypy/interpreter/module.py`_ and `pypy/interpreter/mixedmodule.py`_. Core types supporting the bytecode
- interpreter are defined in `pypy/interpreter/typedef.py`_.
+* :source:`pypy/interpreter` contains the bytecode interpreter: bytecode dispatcher
+ in :source:`pypy/interpreter/pyopcode.py`, frame and code objects in :source:`pypy/interpreter/eval.py` and :source:`pypy/interpreter/pyframe.py`,
+ function objects and argument passing in :source:`pypy/interpreter/function.py` and :source:`pypy/interpreter/argument.py`,
+ the object space interface definition in :source:`pypy/interpreter/baseobjspace.py`, modules in
+ :source:`pypy/interpreter/module.py` and :source:`pypy/interpreter/mixedmodule.py`. Core types supporting the bytecode
+ interpreter are defined in :source:`pypy/interpreter/typedef.py`.
-* `pypy/interpreter/pyparser`_ contains a recursive descent parser,
+* :source:`pypy/interpreter/pyparser` contains a recursive descent parser,
and grammar files that allow it to parse the syntax of various Python
versions. Once the grammar has been processed, the parser can be
translated by the above machinery into efficient code.
-* `pypy/interpreter/astcompiler`_ contains the compiler. This
+* :source:`pypy/interpreter/astcompiler` contains the compiler. This
contains a modified version of the compiler package from CPython
that fixes some bugs and is translatable.
-* `pypy/objspace/std`_ contains the `Standard object space`_. The main file
- is `pypy/objspace/std/objspace.py`_. For each type, the files ``xxxtype.py`` and
+* :source:`pypy/objspace/std` contains the `Standard object space`_. The main file
+ is :source:`pypy/objspace/std/objspace.py`. For each type, the files ``xxxtype.py`` and
``xxxobject.py`` contain respectively the definition of the type and its
(default) implementation.
@@ -227,5 +227,3 @@
.. _unit tests: coding-guide.html#test-design
.. _`directory reference`: index.html#pypy-directory-reference
-
-.. include:: _ref.txt
diff --git a/pypy/doc/getting-started-python.rst b/pypy/doc/getting-started-python.rst
--- a/pypy/doc/getting-started-python.rst
+++ b/pypy/doc/getting-started-python.rst
@@ -304,5 +304,3 @@
.. _`Boehm-Demers-Weiser garbage collector`: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
.. _clr: clr-module.html
.. _`CPythons core language regression tests`: http://buildbot.pypy.org/summary?category=applevel&branch=%3Ctrunk%3E
-
-.. include:: _ref.txt
diff --git a/pypy/doc/getting-started.rst b/pypy/doc/getting-started.rst
--- a/pypy/doc/getting-started.rst
+++ b/pypy/doc/getting-started.rst
@@ -177,6 +177,3 @@
.. _`Using the development tracker`: coding-guide.html#using-development-tracker
.. _bug reports: https://bugs.pypy.org/
-
-
-.. include:: _ref.txt
diff --git a/pypy/doc/glossary.rst b/pypy/doc/glossary.rst
--- a/pypy/doc/glossary.rst
+++ b/pypy/doc/glossary.rst
@@ -167,5 +167,3 @@
.. _Python: http://www.python.org
.. _`RPython Typer`: rtyper.html
.. _`subsystem implementing the Python language`: architecture.html#standard-interpreter
-
-.. include:: _ref.txt
diff --git a/pypy/doc/index.rst b/pypy/doc/index.rst
--- a/pypy/doc/index.rst
+++ b/pypy/doc/index.rst
@@ -115,5 +115,3 @@
.. _`RPython toolchain`: translation.html
.. _`potential project ideas`: project-ideas.html
.. _`more stuff`: project-documentation.html
-
-.. include:: _ref.txt
diff --git a/pypy/doc/interpreter.rst b/pypy/doc/interpreter.rst
--- a/pypy/doc/interpreter.rst
+++ b/pypy/doc/interpreter.rst
@@ -14,7 +14,7 @@
PyPy's bytecode interpreter has a structure reminiscent of CPython's
Virtual Machine: It processes code objects parsed and compiled from
-Python source code. It is implemented in the `pypy/interpreter/`_ directory.
+Python source code. It is implemented in the :source:`pypy/interpreter/` directory.
People familiar with the CPython implementation will easily recognize
similar concepts there. The major differences are the overall usage of
the `object space`_ indirection to perform operations on objects, and
@@ -28,7 +28,7 @@
abstract syntax tree builder and bytecode generator). The latter passes
are based on the ``compiler`` package from the standard library of
CPython, with various improvements and bug fixes. The bytecode compiler
-(living under `pypy/interpreter/astcompiler/`_) is now integrated and is
+(living under :source:`pypy/interpreter/astcompiler/`) is now integrated and is
translated with the rest of PyPy.
Code objects contain
@@ -38,7 +38,7 @@
calling its ``frame.eval()`` method. This main entry point
initialize appropriate namespaces and then interprets each
bytecode instruction. Python's standard library contains
-the `lib-python/2.7/dis.py`_ module which allows to inspection
+the :source:`lib-python/2.7/dis.py` module which allows to inspection
of the virtual machine's bytecode instructions::
>>> import dis
@@ -149,12 +149,12 @@
the actual bytecodes found in a code object. The methods of the ``PyFrame``
class are added in various files:
-- the class ``PyFrame`` is defined in `pypy/interpreter/pyframe.py`_.
+- the class ``PyFrame`` is defined in :source:`pypy/interpreter/pyframe.py`.
-- the file `pypy/interpreter/pyopcode.py`_ add support for all Python opcode.
+- the file :source:`pypy/interpreter/pyopcode.py` add support for all Python opcode.
- nested scope support is added to the ``PyFrame`` class in
- `pypy/interpreter/nestedscope.py`_.
+ :source:`pypy/interpreter/nestedscope.py`.
.. _Code:
@@ -195,7 +195,7 @@
Function and Method classes
----------------------------
-The PyPy ``Function`` class (in `pypy/interpreter/function.py`_)
+The PyPy ``Function`` class (in :source:`pypy/interpreter/function.py`)
represents a Python function. A ``Function`` carries the following
main attributes:
@@ -218,7 +218,7 @@
Arguments Class
--------------------
-The Argument class (in `pypy/interpreter/argument.py`_) is
+The Argument class (in :source:`pypy/interpreter/argument.py`) is
responsible for parsing arguments passed to functions.
Python has rather complex argument-passing concepts:
@@ -257,10 +257,10 @@
Apart from the basic Module used for importing
application-level files there is a more refined
-``MixedModule`` class (see `pypy/interpreter/mixedmodule.py`_)
+``MixedModule`` class (see :source:`pypy/interpreter/mixedmodule.py`)
which allows to define name-value bindings both at application
level and at interpreter level. See the ``__builtin__``
-module's `pypy/module/__builtin__/__init__.py`_ file for an
+module's :source:`pypy/module/__builtin__/__init__.py` file for an
example and the higher level `chapter on Modules in the coding
guide`_.
@@ -275,7 +275,7 @@
A unique PyPy property is the ability to easily cross the barrier
between interpreted and machine-level code (often referred to as
the difference between `interpreter-level and application-level`_).
-Be aware that the according code (in `pypy/interpreter/gateway.py`_)
+Be aware that the according code (in :source:`pypy/interpreter/gateway.py`)
for crossing the barrier in both directions is somewhat
involved, mostly due to the fact that the type-inferring
annotator needs to keep track of the types of objects flowing
@@ -361,7 +361,7 @@
The ``find_metaclass`` interpreter-level hook is invoked
with five arguments from the ``BUILD_CLASS`` opcode implementation
-in `pypy/interpreter/pyopcode.py`_::
+in :source:`pypy/interpreter/pyopcode.py`::
def BUILD_CLASS(f):
w_methodsdict = f.valuestack.pop()
@@ -398,8 +398,6 @@
a wrapped object for its type via a ``getclass`` method and then
calls the type's ``lookup(name)`` function in order to receive a descriptor
function. Most of PyPy's internal object descriptors are defined at the
-end of `pypy/interpreter/typedef.py`_. You can use these definitions
+end of :source:`pypy/interpreter/typedef.py`. You can use these definitions
as a reference for the exact attributes of interpreter classes visible
at application level.
-
-.. include:: _ref.txt
diff --git a/pypy/doc/objspace-proxies.rst b/pypy/doc/objspace-proxies.rst
--- a/pypy/doc/objspace-proxies.rst
+++ b/pypy/doc/objspace-proxies.rst
@@ -61,7 +61,7 @@
----------------------------------------------------
Suppose we want to have a list which stores all operations performed on
-it for later analysis. We can use the small `lib_pypy/tputil.py`_ module to help
+it for later analysis. We can use the small :source:`lib_pypy/tputil.py` module to help
with transparently proxying builtin instances::
from tputil import make_proxy
@@ -113,7 +113,7 @@
tputil helper module
----------------------------
-The `lib_pypy/tputil.py`_ module provides:
+The :source:`lib_pypy/tputil.py` module provides:
* ``make_proxy(controller, type, obj)``: function which
creates a transparent proxy controlled by the given
@@ -171,8 +171,8 @@
to application level code.
Transparent proxies are implemented on top of the `standard object
-space`_, in `pypy/objspace/std/proxy_helpers.py`_, `pypy/objspace/std/proxyobject.py`_ and
-`pypy/objspace/std/transparent.py`_. To use them you will need to pass a
+space`_, in :source:`pypy/objspace/std/proxy_helpers.py`, :source:`pypy/objspace/std/proxyobject.py` and
+:source:`pypy/objspace/std/transparent.py`. To use them you will need to pass a
`--objspace-std-withtproxy`_ option to ``py.py`` or
``translate.py``. This registers implementations named
``W_TransparentXxx`` - which usually correspond to an
@@ -186,5 +186,3 @@
.. [D12.1] `High-Level Backends and Interpreter Feature Prototypes`, PyPy
EU-Report, 2007, http://codespeak.net/pypy/extradoc/eu-report/D12.1_H-L-Backends_and_Feature_Prototypes-2007-03-22.pdf
-
-.. include:: _ref.txt
diff --git a/pypy/doc/objspace.rst b/pypy/doc/objspace.rst
--- a/pypy/doc/objspace.rst
+++ b/pypy/doc/objspace.rst
@@ -52,7 +52,7 @@
The present document gives a description of the above object spaces.
The sources of PyPy contain the various object spaces in the directory
-`pypy/objspace/`_.
+:source:`pypy/objspace/`.
.. _`application-level`: coding-guide.html#application-level
.. _`interpreter-level`: coding-guide.html#interpreter-level
@@ -71,11 +71,11 @@
``getexecutioncontext():``
Return current active execution context
- (`pypy/interpreter/executioncontext.py`_).
+ (:source:`pypy/interpreter/executioncontext.py`).
``getbuiltinmodule(name):``
Return a Module object for the built-in module given by name
- (`pypy/interpreter/module.py`_).
+ (:source:`pypy/interpreter/module.py`).
Operations on Objects in the Object Space
-----------------------------------------
@@ -291,7 +291,7 @@
Introduction
------------
-The Standard Object Space (`pypy/objspace/std/`_) is the direct equivalent of CPython's
+The Standard Object Space (:source:`pypy/objspace/std/`) is the direct equivalent of CPython's
object library (the "Objects/" subdirectory in the distribution). It is an
implementation of the common Python types in a lower-level language.
@@ -339,7 +339,7 @@
Object types
------------
-The larger part of the `pypy/objspace/std/`_ package defines and implements the
+The larger part of the :source:`pypy/objspace/std/` package defines and implements the
library of Python's standard built-in object types. Each type (int, float,
list, tuple, str, type, etc.) is typically implemented by two modules:
@@ -348,17 +348,17 @@
* the *implementation* module, called ``xxxobject.py``.
The ``xxxtype.py`` module basically defines the type object itself. For
-example, `pypy/objspace/std/listtype.py`_ contains the specification of the object you get when
-you type ``list`` in a PyPy prompt. `pypy/objspace/std/listtype.py`_ enumerates the methods
+example, :source:`pypy/objspace/std/listtype.py` contains the specification of the object you get when
+you type ``list`` in a PyPy prompt. :source:`pypy/objspace/std/listtype.py` enumerates the methods
specific to lists, like ``append()``.
A particular method implemented by all types is the ``__new__()`` special
method, which in Python's new-style-classes world is responsible for creating
an instance of the type. In PyPy, ``__new__()`` locates and imports the module
implementing *instances* of the type, and creates such an instance based on the
-arguments the user supplied to the constructor. For example, `pypy/objspace/std/tupletype.py`_
+arguments the user supplied to the constructor. For example, :source:`pypy/objspace/std/tupletype.py`
defines ``__new__()`` to import the class ``W_TupleObject`` from
-`pypy/objspace/std/tupleobject.py`_ and instantiate it. The `pypy/objspace/std/tupleobject.py`_ then contains a
+:source:`pypy/objspace/std/tupleobject.py` and instantiate it. The :source:`pypy/objspace/std/tupleobject.py` then contains a
"real" implementation of tuples: the way the data is stored in the
``W_TupleObject`` class, how the operations work, etc.
@@ -374,9 +374,9 @@
same Python type. PyPy knows that (e.g.) the application-level type of
its interpreter-level ``W_StringObject`` instances is str because
there is a ``typedef`` class attribute in ``W_StringObject`` which
-points back to the string type specification from `pypy/objspace/std/stringtype.py`_; all
+points back to the string type specification from :source:`pypy/objspace/std/stringtype.py`; all
other implementations of strings use the same ``typedef`` from
-`pypy/objspace/std/stringtype.py`_.
+:source:`pypy/objspace/std/stringtype.py`.
For other examples of multiple implementations of the same Python type,
see `Standard Interpreter Optimizations`_.
@@ -390,7 +390,7 @@
The Standard Object Space allows multiple object implementations per
Python type - this is based on multimethods_. For a description of the
multimethod variant that we implemented and which features it supports,
-see the comment at the start of `pypy/objspace/std/multimethod.py`_. However, multimethods
+see the comment at the start of :source:`pypy/objspace/std/multimethod.py`. However, multimethods
alone are not enough for the Standard Object Space: the complete picture
spans several levels in order to emulate the exact Python semantics.
@@ -491,7 +491,7 @@
Introduction
------------
-The task of the FlowObjSpace (the source is at `pypy/objspace/flow/`_) is to generate a control-flow graph from a
+The task of the FlowObjSpace (the source is at :source:`pypy/objspace/flow/`) is to generate a control-flow graph from a
function. This graph will also contain a trace of the individual operations, so
that it is actually just an alternate representation for the function.
@@ -570,5 +570,3 @@
PyPy can do for your objects`_.
.. _`What PyPy can do for your objects`: objspace-proxies.html
-
-.. include:: _ref.txt
diff --git a/pypy/doc/parser.rst b/pypy/doc/parser.rst
--- a/pypy/doc/parser.rst
+++ b/pypy/doc/parser.rst
@@ -12,7 +12,7 @@
---------
At the moment, the tokenizer is implemented as a single function
-(``generate_tokens`` in `pypy/interpreter/pyparser/pytokenizer.py`_) that builds
+(``generate_tokens`` in :source:`pypy/interpreter/pyparser/pytokenizer.py`) that builds
a list of tokens. The tokens are then fed to the parser.
Parser
@@ -24,7 +24,7 @@
***************************
The python grammar is built at startup from the pristine CPython grammar file
-(see `pypy/interpreter/pyparser/metaparser.py`_). The grammar builder first
+(see :source:`pypy/interpreter/pyparser/metaparser.py`). The grammar builder first
represents the grammar as rules corresponding to a set of Nondeterministic
Finite Automatons (NFAs). It then converts them to a set of Deterministic
Finite Automatons (DFAs). The difference between a NFA and a DFA is that a NFA
@@ -32,7 +32,7 @@
have one. DFAs are therefore more limiting, but far more efficient to use in
parsing. Finally, the assigns the grammar builder assigns each DFA state a
number and packs them into a list for the parser to use. The final product is
-an instance of the ``Grammar`` class in `pypy/interpreter/pyparser/parser.py`_.
+an instance of the ``Grammar`` class in :source:`pypy/interpreter/pyparser/parser.py`.
Parser implementation
*********************
@@ -48,11 +48,11 @@
**************
The glue code between the tokenizer and the parser as well as extra Python
-specific code is in `pypy/interpreter/pyparser/pyparse.py`_. The
+specific code is in :source:`pypy/interpreter/pyparser/pyparse.py`. The
``parse_source`` method takes a string of Python code and returns the parse
tree. It also detects the coding cookie if there is one and decodes the source.
Note that __future__ imports are handled before the parser is invoked by
-manually parsing the source in `pypy/interpreter/pyparser/future.py`_.
+manually parsing the source in :source:`pypy/interpreter/pyparser/future.py`.
Compiler
--------
@@ -63,21 +63,21 @@
Building AST
************
-Python's AST is described in `pypy/interpreter/astcompiler/tools/Python.asdl`_.
-From this definition, `pypy/interpreter/astcompiler/tools/asdl_py.py`_ generates
-`pypy/interpreter/astcompiler/ast.py`_, which RPython classes for the compiler
+Python's AST is described in :source:`pypy/interpreter/astcompiler/tools/Python.asdl`.
+From this definition, :source:`pypy/interpreter/astcompiler/tools/asdl_py.py` generates
+:source:`pypy/interpreter/astcompiler/ast.py`, which RPython classes for the compiler
as well as bindings to application level code for the AST. Some custom
extensions to the AST classes are in
-`pypy/interpreter/astcompiler/asthelpers.py`_.
+:source:`pypy/interpreter/astcompiler/asthelpers.py`.
-`pypy/interpreter/astcompiler/astbuilder.py`_ is responsible for converting
+:source:`pypy/interpreter/astcompiler/astbuilder.py` is responsible for converting
parse trees into AST. It walks down the parse tree building nodes as it goes.
The result is a toplevel ``mod`` node.
AST Optimization
****************
-`pypy/interpreter/astcompiler/optimize.py`_ contains the AST optimizer. It does
+:source:`pypy/interpreter/astcompiler/optimize.py` contains the AST optimizer. It does
constant folding of expressions, and other simple transformations like making a
load of the name "None" into a constant.
@@ -85,7 +85,7 @@
***************
Before writing bytecode, a symbol table is built in
-`pypy/interpreter/astcompiler/symtable.py`_. It determines if every name in the
+:source:`pypy/interpreter/astcompiler/symtable.py`. It determines if every name in the
source is local, implicitly global (no global declaration), explicitly global
(there's a global declaration of the name in the scope), a cell (the name in
used in nested scopes), or free (it's used in a nested function).
@@ -93,11 +93,9 @@
Bytecode generation
*******************
-Bytecode is emitted in `pypy/interpreter/astcompiler/codegen.py`_. Each
+Bytecode is emitted in :source:`pypy/interpreter/astcompiler/codegen.py`. Each
bytecode is represented temporarily by the ``Instruction`` class in
-`pypy/interpreter/astcompiler/assemble.py`_. After all bytecodes have been
+:source:`pypy/interpreter/astcompiler/assemble.py`. After all bytecodes have been
emitted, it's time to build the code object. Jump offsets and bytecode
information like the line number table and stack depth are computed. Finally,
everything is passed to a brand new ``PyCode`` object.
-
-.. include:: _ref.txt
diff --git a/pypy/doc/project-documentation.rst b/pypy/doc/project-documentation.rst
--- a/pypy/doc/project-documentation.rst
+++ b/pypy/doc/project-documentation.rst
@@ -161,5 +161,3 @@
* :ref:`genindex`
* :ref:`search`
* :ref:`glossary`
-
-.. include:: _ref.txt
diff --git a/pypy/doc/stackless.rst b/pypy/doc/stackless.rst
--- a/pypy/doc/stackless.rst
+++ b/pypy/doc/stackless.rst
@@ -29,7 +29,7 @@
on 32-bit or a complete megabyte on 64-bit. Moreover, the feature is
only available (so far) on x86 and x86-64 CPUs; for other CPUs you need
to add a short page of custom assembler to
-`rpython/translator/c/src/stacklet/`_.
+:source:`rpython/translator/c/src/stacklet/`.
Theory
@@ -185,7 +185,7 @@
Greenlets
+++++++++
-Greenlets are implemented on top of continulets in `lib_pypy/greenlet.py`_.
+Greenlets are implemented on top of continulets in :source:`lib_pypy/greenlet.py`.
See the official `documentation of the greenlets`_.
Note that unlike the CPython greenlets, this version does not suffer
@@ -271,7 +271,7 @@
Continulets are internally implemented using stacklets, which is the
generic RPython-level building block for "one-shot continuations". For
more information about them please see the documentation in the C source
-at `rpython/translator/c/src/stacklet/stacklet.h`_.
+at :source:`rpython/translator/c/src/stacklet/stacklet.h`.
The module ``rpython.rlib.rstacklet`` is a thin wrapper around the above
functions. The key point is that new() and switch() always return a
@@ -411,5 +411,3 @@
.. _`Stackless Python`: http://www.stackless.com
.. _`documentation of the greenlets`: http://packages.python.org/greenlet/
-
-.. include:: _ref.txt
More information about the pypy-commit
mailing list