Author: Manuel Jacob
Branch: rpython-doc
Changeset: r61685:596e8be030a5
Date: 2013-02-23 16:46 +0100
http://bitbucket.org/pypy/pypy/changeset/596e8be030a5/
Log: Make use of sphinx' extlinks extension.
diff --git a/rpython/doc/conf.py b/rpython/doc/conf.py
--- a/rpython/doc/conf.py
+++ b/rpython/doc/conf.py
@@ -25,7 +25,7 @@
# Add any Sphinx extension module names here, as strings. They can be
extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.graphviz']
+extensions = ['sphinx.ext.extlinks', 'sphinx.ext.graphviz']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -240,3 +240,5 @@
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
+
+extlinks = {'source': ('https://bitbucket.org/pypy/pypy/src/default/%s', '')}
diff --git a/rpython/doc/garbage_collection.rst
b/rpython/doc/garbage_collection.rst
--- a/rpython/doc/garbage_collection.rst
+++ b/rpython/doc/garbage_collection.rst
@@ -42,7 +42,7 @@
Two arenas of equal size, with only one arena in use and getting filled
with new objects. When the arena is full, the live objects are copied
into the other arena using Cheney's algorithm. The old arena is then
-cleared. See `rpython/memory/gc/semispace.py`_.
+cleared. See :source:`rpython/memory/gc/semispace.py`.
On Unix the clearing is done by reading ``/dev/zero`` into the arena,
which is extremely memory efficient at least on Linux: it lets the
@@ -55,7 +55,7 @@
Generational GC
---------------
-This is a two-generations GC. See `rpython/memory/gc/generation.py`_.
+This is a two-generations GC. See :source:`rpython/memory/gc/generation.py`.
It is implemented as a subclass of the Semispace copying collector. It
adds a nursery, which is a chunk of the current semispace. Its size is
@@ -86,7 +86,7 @@
Each generation is collected much less often than the previous one. The
division of the generations is slightly more complicated than just
nursery / semispace / external; see the diagram at the start of the
-source code, in `rpython/memory/gc/hybrid.py`_.
+source code, in :source:`rpython/memory/gc/hybrid.py`.
Mark & Compact GC
-----------------
@@ -161,7 +161,7 @@
to the old stage. The dying case 2 objects are immediately freed.
- The old stage is an area of memory containing old (small) objects. It
- is handled by `rpython/memory/gc/minimarkpage.py`_. It is organized
+ is handled by :source:`rpython/memory/gc/minimarkpage.py`. It is organized
as "arenas" of 256KB or 512KB, subdivided into "pages" of 4KB or 8KB.
Each page can either be free, or contain small objects of all the same
size. Furthermore at any point in time each object location can be
@@ -209,5 +209,3 @@
next minor collection, we move it there, and so its id() and hash()
are preserved. If the object dies then the pre-reserved location
becomes free garbage, to be collected at the next major collection.
-
-.. include:: _ref.txt
diff --git a/rpython/doc/rlib.rst b/rpython/doc/rlib.rst
--- a/rpython/doc/rlib.rst
+++ b/rpython/doc/rlib.rst
@@ -7,18 +7,18 @@
.. contents::
-This page lists some of the modules in `rpython/rlib`_ together with some hints
+This page lists some of the modules in :source:`rpython/rlib` together with
some hints
for what they can be used for. The modules here will make up some general
library useful for RPython programs (since most of the standard library modules
are not RPython). Most of these modules are somewhat rough still and are likely
to change at some point. Usually it is useful to look at the tests in
-`rpython/rlib/test`_ to get an impression of how to use a module.
+:source:`rpython/rlib/test` to get an impression of how to use a module.
``listsort``
============
-The `rpython/rlib/listsort.py`_ module contains an implementation of the
timsort sorting algorithm
+The :source:`rpython/rlib/listsort.py` module contains an implementation of
the timsort sorting algorithm
(the sort method of lists is not RPython). To use it, subclass from the
``listsort.TimSort`` class and override the ``lt`` method to change the
comparison behaviour. The constructor of ``TimSort`` takes a list as an
@@ -30,7 +30,7 @@
``nonconst``
============
-The `rpython/rlib/nonconst.py`_ module is useful mostly for tests. The `flow
object space`_ and
+The :source:`rpython/rlib/nonconst.py` module is useful mostly for tests. The
`flow object space`_ and
the `annotator`_ do quite some constant folding, which is sometimes not desired
in a test. To prevent constant folding on a certain value, use the ``NonConst``
class. The constructor of ``NonConst`` takes an arbitrary value. The instance
of
@@ -44,7 +44,7 @@
``objectmodel``
===============
-The `rpython/rlib/objectmodel.py`_ module is a mixed bag of various
functionality. Some of the
+The :source:`rpython/rlib/objectmodel.py` module is a mixed bag of various
functionality. Some of the
more useful ones are:
``ComputedIntSymbolic``:
@@ -94,7 +94,7 @@
``rarithmetic``
===============
-The `rpython/rlib/rarithmetic.py`_ module contains functionality to handle the
small differences
+The :source:`rpython/rlib/rarithmetic.py` module contains functionality to
handle the small differences
in the behaviour of arithmetic code in regular Python and RPython code. Most of
them are already described in the `coding guide`_
@@ -104,7 +104,7 @@
``rbigint``
===========
-The `rpython/rlib/rbigint.py`_ module contains a full RPython implementation
of the Python ``long``
+The :source:`rpython/rlib/rbigint.py` module contains a full RPython
implementation of the Python ``long``
type (which itself is not supported in RPython). The ``rbigint`` class contains
that implementation. To construct ``rbigint`` instances use the static methods
``fromint``, ``frombool``, ``fromfloat`` and ``fromdecimalstr``. To convert
back
@@ -118,7 +118,7 @@
``rrandom``
===========
-The `rpython/rlib/rrandom.py`_ module contains an implementation of the
mersenne twister random
+The :source:`rpython/rlib/rrandom.py` module contains an implementation of the
mersenne twister random
number generator. It contains one class ``Random`` which most importantly has a
``random`` method which returns a pseudo-random floating point number between
0.0 and 1.0.
@@ -126,7 +126,7 @@
``rsocket``
===========
-The `rpython/rlib/rsocket.py`_ module contains an RPython implementation of
the functionality of
+The :source:`rpython/rlib/rsocket.py` module contains an RPython
implementation of the functionality of
the socket standard library with a slightly different interface. The
difficulty with the Python socket API is that addresses are not "well-typed"
objects: depending on the address family they are tuples, or strings, and
@@ -137,7 +137,7 @@
``streamio``
============
-The `rpython/rlib/streamio.py`_ contains an RPython stream I/O implementation
(which was started
+The :source:`rpython/rlib/streamio.py` contains an RPython stream I/O
implementation (which was started
by Guido van Rossum as `sio.py`_ in the CPython sandbox as a prototype for the
upcoming new file implementation in Python 3000).
@@ -146,7 +146,7 @@
``unroll``
==========
-The `rpython/rlib/unroll.py`_ module most importantly contains the function
``unrolling_iterable``
+The :source:`rpython/rlib/unroll.py` module most importantly contains the
function ``unrolling_iterable``
which wraps an iterator. Looping over the iterator in RPython code will not
produce a loop in the resulting flow graph but will unroll the loop instead.
@@ -154,7 +154,7 @@
``parsing``
===========
-The `rpython/rlib/parsing/`_ module is a still in-development module to
generate tokenizers and
+The :source:`rpython/rlib/parsing/` module is a still in-development module to
generate tokenizers and
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
@@ -295,7 +295,7 @@
The parsing process builds up a tree consisting of instances of ``Symbol`` and
``Nonterminal``, the former corresponding to tokens, the latter to nonterminal
-symbols. Both classes live in the `rpython/rlib/parsing/tree.py`_ module. You
can use
+symbols. Both classes live in the :source:`rpython/rlib/parsing/tree.py`
module. You can use
the ``view()`` method ``Nonterminal`` instances to get a pygame view of the
parse tree.
@@ -310,7 +310,7 @@
++++++++
To write tree visitors for the parse trees that are RPython, there is a special
-baseclass ``RPythonVisitor`` in `rpython/rlib/parsing/tree.py`_ to use. If your
+baseclass ``RPythonVisitor`` in :source:`rpython/rlib/parsing/tree.py` to use.
If your
class uses this, it will grow a ``dispatch(node)`` method, that calls an
appropriate ``visit_<symbol>`` method, depending on the ``node`` argument. Here
the <symbol> is replaced by the ``symbol`` attribute of the visited node.
@@ -648,5 +648,3 @@
.. _`Prolog interpreter`: https://bitbucket.org/cfbolz/pyrolog/
.. _`json format`: http://www.json.org
-
-.. include:: _ref.txt
diff --git a/rpython/doc/rtyper.rst b/rpython/doc/rtyper.rst
--- a/rpython/doc/rtyper.rst
+++ b/rpython/doc/rtyper.rst
@@ -4,7 +4,7 @@
.. contents::
-The RPython Typer lives in the directory `rpython/rtyper/`_.
+The RPython Typer lives in the directory :source:`rpython/rtyper/`.
Overview
@@ -66,7 +66,7 @@
each operation. In both cases the analysis of an operation depends on the
annotations of its input arguments. This is reflected in the usage of the same
``__extend__`` syntax in the source files (compare e.g.
-`rpython/annotator/binaryop.py`_ and `rpython/rtyper/rint.py`_).
+:source:`rpython/annotator/binaryop.py` and :source:`rpython/rtyper/rint.py`).
The analogy stops here, though: while it runs, the Annotator is in the middle
of computing the annotations, so it might need to reflow and generalize until
@@ -104,7 +104,7 @@
implementations for the same high-level operations. This is the reason for
turning representations into explicit objects.
-The base Repr class is defined in `rpython/rtyper/rmodel.py`_. Most of the
+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
getrepr() of the RTyper will build and cache a single Repr instance per
SomeXxx() instance; moreover, two SomeXxx() instances that are equal get the
@@ -131,9 +131,9 @@
The RPython Typer uses a standard low-level model which we believe can
correspond rather directly to various target languages such as C.
This model is implemented in the first part of
-`rpython/rtyper/lltypesystem/lltype.py`_.
+:source:`rpython/rtyper/lltypesystem/lltype.py`.
-The second part of `rpython/rtyper/lltypesystem/lltype.py`_ is a runnable
+The second part of :source:`rpython/rtyper/lltypesystem/lltype.py` is a
runnable
implementation of these types, for testing purposes. It allows us to write
and test plain Python code using a malloc() function to obtain and manipulate
structures and arrays. This is useful for example to implement and test
@@ -191,7 +191,7 @@
types like list in this elementary world. The ``malloc()`` function is a kind
of placeholder, which must eventually be provided by the code generator for the
target platform; but as we have just seen its Python implementation in
-`rpython/rtyper/lltypesystem/lltype.py`_ works too, which is primarily useful
for
+:source:`rpython/rtyper/lltypesystem/lltype.py` works too, which is primarily
useful for
testing, interactive exploring, etc.
The argument to ``malloc()`` is the structure type directly, but it returns a
@@ -316,7 +316,7 @@
with care: the bigger structure of which they are part of could be freed while
the Ptr to the substructure is still in use. In general, it is a good idea to
avoid passing around pointers to inlined substructures of malloc()ed
structures.
-(The testing implementation of `rpython/rtyper/lltypesystem/lltype.py`_ checks
to some
+(The testing implementation of :source:`rpython/rtyper/lltypesystem/lltype.py`
checks to some
extent that you are not trying to use a pointer to a structure after its
container has been freed, using weak references. But pointers to non-GC
structures are not officially meant to be weak references: using them after
what
@@ -429,7 +429,7 @@
change needed to the Annotator to allow it to perform type inference of our
very-low-level snippets of code.
-See for example `rpython/rtyper/rlist.py`_.
+See for example :source:`rpython/rtyper/rlist.py`.
.. _`oo type`:
@@ -441,10 +441,10 @@
targeting low level backends such as C, but it is not good
enough for targeting higher level backends such as .NET CLI or Java
JVM, so a new object oriented model has been introduced. This model is
-implemented in the first part of `rpython/rtyper/ootypesystem/ootype.py`_.
+implemented in the first part of
:source:`rpython/rtyper/ootypesystem/ootype.py`.
As for the low-level typesystem, the second part of
-`rpython/rtyper/ootypesystem/ootype.py`_ is a runnable implementation of
+:source:`rpython/rtyper/ootypesystem/ootype.py` is a runnable implementation of
these types, for testing purposes.
@@ -751,7 +751,7 @@
The LLInterpreter is a simple piece of code that is able to interpret flow
graphs. This is very useful for testing purposes, especially if you work on
the RPython Typer. The most useful interface for it is the ``interpret``
-function in the file `rpython/rtyper/test/test_llinterp.py`_. It takes as
+function in the file :source:`rpython/rtyper/test/test_llinterp.py`. It takes
as
arguments a function and a list of arguments with which the function is
supposed to be called. Then it generates the flow graph, annotates it
according to the types of the arguments you passed to it and runs the
@@ -791,5 +791,3 @@
assert res == ~3
.. _annotator: translation.html#the-annotation-pass
-
-.. include:: _ref.txt
diff --git a/rpython/doc/translation.rst b/rpython/doc/translation.rst
--- a/rpython/doc/translation.rst
+++ b/rpython/doc/translation.rst
@@ -90,7 +90,7 @@
(although these steps are not quite as distinct as you might think from
this presentation).
-There is an `interactive interface`_ called `rpython/bin/translatorshell.py`_
to the
+There is an `interactive interface`_ called
:source:`rpython/bin/translatorshell.py` to the
translation process which allows you to interactively work through these
stages.
@@ -116,7 +116,7 @@
which are the basic data structures of the translation
process.
-All these types are defined in `rpython/flowspace/model.py`_ (which is a rather
+All these types are defined in :source:`rpython/flowspace/model.py` (which is
a rather
important module in the PyPy source base, to reinforce the point).
The flow graph of a function is represented by the class ``FunctionGraph``.
@@ -744,5 +744,3 @@
translation step to declare that it needs to be able to call each of a
collection of functions (which may refer to each other in a mutually
recursive fashion) and annotate and rtype them all at once.
-
-.. include:: _ref.txt
_______________________________________________
pypy-commit mailing list
pypy-commit@python.org
http://mail.python.org/mailman/listinfo/pypy-commit
