[pypy-commit] cffi default: Add some more "codeblock:: python"

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r2056:ef803221d8dc
Date: 2015-05-19 18:57 +0200
http://bitbucket.org/cffi/cffi/changeset/ef803221d8dc/

Log:	Add some more "codeblock:: python"

diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -5,7 +5,9 @@
 There are three or four different ways to use CFFI in a project.
 In order of complexity:
 
-* The **"in-line", "ABI mode"**::
+* The **"in-line", "ABI mode"**:
+
+  .. code-block:: python
 
     import cffi
 
@@ -18,7 +20,9 @@
 .. _out-of-line-abi:
 
 * The **"out-of-line",** but still **"ABI mode",** useful to organize
-  the code and reduce the import time::
+  the code and reduce the import time:
+
+  .. code-block:: python
 
     # in a separate file "package/foo_build.py"
     import cffi
@@ -31,7 +35,9 @@
         ffi.compile()
 
   Running ``python foo_build.py`` produces a file ``_foo.py``, which
-  can then be imported in the main program::
+  can then be imported in the main program:
+
+  .. code-block:: python
 
     from package._foo import ffi
     lib = ffi.dlopen("libpath")
@@ -42,7 +48,9 @@
 
 * The **"out-of-line", "API mode"** gives you the most flexibility to
   access a C library at the level of C, instead of at the binary
-  level::
+  level:
+
+  .. code-block:: python
 
     # in a separate file "package/foo_build.py"
     import cffi
@@ -57,7 +65,9 @@
   Running ``python foo_build.py`` produces a file ``_foo.c`` and
   invokes the C compiler to turn it into a file ``_foo.so`` (or
   ``_foo.pyd`` or ``_foo.dylib``).  It is a C extension module which
-  can be imported in the main program::
+  can be imported in the main program:
+
+  .. code-block:: python
 
     from package._foo import ffi, lib
     # no ffi.dlopen()
@@ -68,7 +78,9 @@
 
 * Finally, you can (but don't have to) use CFFI's **Distutils** or
   **Setuptools integration** when writing a ``setup.py``.  For
-  Distutils (only in out-of-line API mode)::
+  Distutils (only in out-of-line API mode):
+
+  .. code-block:: python
 
     # setup.py (requires CFFI to be installed first)
     from distutils.core import setup
@@ -81,7 +93,9 @@
     )
 
   For Setuptools (out-of-line, but works in ABI or API mode;
-  recommended)::
+  recommended):
+
+  .. code-block:: python
 
     # setup.py (with automatic dependency tracking)
     from setuptools import setup
@@ -309,7 +323,9 @@
 ``source_extension``, defaulting to ``".c"``.  The file generated will
 be actually called ``module_name + source_extension``.  Example for
 C++ (but note that there are still a few known issues of C-versus-C++
-compatibility)::
+compatibility):
+
+.. code-block:: python
 
     ffi.set_source("mymodule", '''
     extern "C" {
@@ -571,7 +587,9 @@
 One remaining use case for ``ffi.verify()`` would be the following
 hack to find explicitly the size of any type, in bytes, and have it
 available in Python immediately (e.g. because it is needed in order to
-write the rest of the build script)::
+write the rest of the build script):
+
+.. code-block:: python
 
     ffi = cffi.FFI()
     ffi.cdef("const int mysize;")
@@ -652,7 +670,9 @@
 consider moving to the out-of-line approach new in 1.0.  Here are the
 steps.
 
-**ABI mode:** if your CFFI project uses::
+**ABI mode** if your CFFI project uses ``ffi.dlopen()``:
+
+.. code-block:: python
 
     import cffi
 
@@ -668,7 +688,9 @@
 .. __: distutils-setuptools_
 
 
-**API mode:** if your CFFI project uses::
+**API mode** if your CFFI project uses ``ffi.verify()``:
+
+.. code-block:: python
 
     import cffi
 
@@ -689,7 +711,9 @@
 
 The following example should work both with old (pre-1.0) and new
 versions of CFFI---supporting both is important to run on PyPy,
-because CFFI 1.0 does not work in PyPy < 2.6::
+because CFFI 1.0 does not work in PyPy < 2.6:
+
+.. code-block:: python
 
     # in a separate file "package/foo_build.py"
     import cffi
@@ -710,7 +734,9 @@
     if __name__ == "__main__":
         ffi.compile()
 
-And in the main program::
+And in the main program:
+
+.. code-block:: python
 
     try:
         from package._foo import ffi, lib
@@ -723,7 +749,9 @@
 
 Writing a ``setup.py`` script that works both with CFFI 0.9 and 1.0
 requires explicitly checking the version of CFFI that we can have---it
-is hard-coded as a built-in module in PyPy::
+is hard-coded as a built-in module in PyPy:
+
+.. code-block:: python
 
     if '_cffi_backend' in sys.builtin_module_names:   # PyPy
         import _cffi_backend
@@ -732,7 +760,9 @@
         requires_cffi = "cffi>=1.0.0"
 
 Then we use the ``requires_cffi`` variable to give different arguments to
-``setup()`` as needed, e.g.::
+``setup()`` as needed, e.g.:
+
+.. code-block:: python
 
     if requires_cffi.startswith("cffi==0."):
         # backward compatibility: we have "cffi==0.*"
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -83,7 +83,9 @@
 For distribution purposes, remember that there is a new
 ``_simple_example.py`` file generated.  You can either include it
 statically within your project's source files, or, with Setuptools,
-you can say in the ``setup.py``::
+you can say in the ``setup.py``:
+
+.. code-block:: python
 
     from setuptools import setup
 
diff --git a/doc/source/using.rst b/doc/source/using.rst
--- a/doc/source/using.rst
+++ b/doc/source/using.rst
@@ -57,7 +57,9 @@
 ownership, so you must keep it alive.  As soon as you forget it, then
 the casted pointer will point to garbage!  In other words, the ownership
 rules are attached to the *wrapper* cdata objects: they are not, and
-cannot, be attached to the underlying raw memory.)  Example::
+cannot, be attached to the underlying raw memory.)  Example:
+
+.. code-block:: python
 
     global_weakkeydict = weakref.WeakKeyDictionary()
 
@@ -102,7 +104,9 @@
 place to keep alive the original pointer object (returned by
 ``ffi.new()``).
 
-Example::
+Example:
+
+.. code-block:: python
 
     # void somefunction(int *);
 
@@ -184,7 +188,9 @@
 it all the time.
 
 The C99 variable-sized structures are supported too, as long as the
-initializer says how long the array should be::
+initializer says how long the array should be:
+
+.. code-block:: python
 
     # typedef struct { int x; int y[]; } foo_t;
 
@@ -267,7 +273,9 @@
 
 When calling C functions, passing arguments follows mostly the same
 rules as assigning to structure fields, and the return value follows the
-same rules as reading a structure field.  For example::
+same rules as reading a structure field.  For example:
+
+.. code-block:: python
 
     # int foo(short a, int b);
 
@@ -276,7 +284,9 @@
 
 You can pass to ``char *`` arguments a normal Python string (but don't
 pass a normal Python string to functions that take a ``char *``
-argument and may mutate it!)::
+argument and may mutate it!):
+
+.. code-block:: python
 
     # size_t strlen(const char *);
 
@@ -286,14 +296,18 @@
 in general, there is no difference between C argument declarations that
 use ``type *`` or ``type[]``.  For example, ``int *`` is fully
 equivalent to ``int[]`` or ``int[5]``.  So you can pass an ``int *`` as
-a list of integers::
+a list of integers:
+
+.. code-block:: python
 
     # void do_something_with_array(int *array);
 
     lib.do_something_with_array([1, 2, 3, 4, 5])
 
 CFFI supports passing and returning structs to functions and callbacks.
-Example::
+Example:
+
+.. code-block:: python
 
     # struct foo_s { int a, b; };
     # struct foo_s function_returning_a_struct(void);
@@ -319,7 +333,9 @@
 function>``).  This means you cannot e.g. pass them to some other C
 function expecting a function pointer argument.  Only ``ffi.typeof()``
 works on them.  If you really need a cdata pointer to the function,
-use the following workaround::
+use the following workaround:
+
+.. code-block:: python
   
     ffi.cdef(""" int (*foo)(int a, int b); """)
 
@@ -335,18 +351,22 @@
 all the arguments passed in the variable part *must* be cdata objects.
 This is because it would not be possible to guess, if you wrote this::
 
-    lib.printf("hello, %d\n", 42)
+    lib.printf("hello, %d\n", 42)   # doesn't work!
 
 that you really meant the 42 to be passed as a C ``int``, and not a
 ``long`` or ``long long``.  The same issue occurs with ``float`` versus
 ``double``.  So you have to force cdata objects of the C type you want,
-if necessary with ``ffi.cast()``::
+if necessary with ``ffi.cast()``:
+
+.. code-block:: python
   
     lib.printf("hello, %d\n", ffi.cast("int", 42))
     lib.printf("hello, %ld\n", ffi.cast("long", 42))
     lib.printf("hello, %f\n", ffi.cast("double", 42))
 
-But of course::
+But of course:
+
+.. code-block:: python
 
     lib.printf("hello, %s\n", ffi.new("char[]", "world"))
 
@@ -400,7 +420,9 @@
 Note that callbacks of a variadic function type are not supported.  A
 workaround is to add custom C code.  In the following example, a
 callback gets a first argument that counts how many extra ``int``
-arguments are passed::
+arguments are passed:
+
+.. code-block:: python
 
     # file "example_build.py"
 
@@ -427,7 +449,7 @@
         }
     """)
 
-::
+.. code-block:: python
     
     # file "example.py"
 
@@ -450,7 +472,9 @@
 and the C-level callback is made to return a default value.
 
 The returned value in case of errors is 0 or null by default, but can be
-specified with the ``error`` keyword argument to ``ffi.callback()``::
+specified with the ``error`` keyword argument to ``ffi.callback()``:
+
+.. code-block:: python
 
     @ffi.callback("int(int, int)", error=-1)
 
@@ -588,7 +612,9 @@
 accepts a C type can receive either a string or a pre-parsed ``ctype``
 object (and because of caching of the string, there is no real
 performance difference).  It can still be useful in writing typechecks,
-e.g.::
+e.g.:
+
+.. code-block:: python
   
     def myfunction(ptr):
         assert ffi.typeof(ptr) is ffi.typeof("foo_t*")