Ticket #13339: trac_13339-headers.patch

File trac_13339-headers.patch, 51.5 KB (added by jpflori, 10 years ago)

  • sage/ext/gen_interpreters.py 

    # HG changeset patch
# User Jean-Pierre Flori <jean-pierre.flori@ssi.gouv.fr>
# Date 1344157525 -7200
# Node ID 192526852a00d85b19760045ae32daef50d082a5
# Parent  361d834fbcd60757f8d71f636c4c13d5dac1df6a
#13339: generate headers file for interp_*.c

diff --git a/sage/ext/gen_interpreters.py b/sage/ext/gen_interpreters.py
    a b  
    129129
    130130    Indents each line in text by n spaces.
    131131
    132     EXAMPLES:
     132    EXAMPLES::
     133
    133134        sage: from sage.ext.gen_interpreters import indent_lines
    134135        sage: indent_lines(3, "foo")
    135136        '   foo'
    … …  
    159160    template on each call; don't use it in situations where
    160161    performance is important.)
    161162
    162     EXAMPLES:
     163    EXAMPLES::
     164
    163165        sage: from sage.ext.gen_interpreters import je
    164166        sage: je("{{ a }} > {{ b }} * {{ c }}", a='"a suffusion of yellow"', b=3, c=7)
    165167        u'"a suffusion of yellow" > 3 * 7'
    … …  
    223225        A string giving variable declarations that must be local variables
    224226        in Cython methods using this storage type.
    225227
    226         EXAMPLES:
     228        EXAMPLES::
     229
    227230            sage: from sage.ext.gen_interpreters import *
    228231            sage: ty_double.class_member_declarations
    229232            ''
    … …  
    259262        of output locations are passed into the instruction and the
    260263        instruction writes outputs directly in the final location.
    261264
    262         EXAMPLES:
     265        EXAMPLES::
     266
    263267            sage: from sage.ext.gen_interpreters import *
    264268            sage: ty_double.cheap_copies()
    265269            True
    … …  
    280284        like "generate an incref" and "generate a decref".  But as
    281285        long as we only support Python, this way is probably simpler.)
    282286
    283         EXAMPLES:
     287        EXAMPLES::
     288
    284289            sage: from sage.ext.gen_interpreters import *
    285290            sage: ty_double.python_refcounted()
    286291            False
    … …  
    293298        r"""
    294299        Gives the Cython type for a single value of this type (as a string).
    295300
    296         EXAMPLES:
     301        EXAMPLES::
     302
    297303            sage: from sage.ext.gen_interpreters import *
    298304            sage: ty_double.cython_decl_type()
    299305            'double'
    … …  
    309315        Gives the Cython type for referring to an array of values of
    310316        this type (as a string).
    311317
    312         EXAMPLES:
     318        EXAMPLES::
     319
    313320            sage: from sage.ext.gen_interpreters import *
    314321            sage: ty_double.cython_array_type()
    315322            'double*'
    … …  
    331338        generate empty loops, which are ugly and potentially might not
    332339        be optimized away.)
    333340
    334         EXAMPLES:
     341        EXAMPLES::
     342
    335343            sage: from sage.ext.gen_interpreters import *
    336344            sage: ty_double.needs_cython_init_clear()
    337345            False
    … …  
    346354        r"""
    347355        Gives the C type for a single value of this type (as a string).
    348356
    349         EXAMPLES:
     357        EXAMPLES::
     358
    350359            sage: from sage.ext.gen_interpreters import *
    351360            sage: ty_double.c_decl_type()
    352361            'double'
    … …  
    362371        Gives the C type for a pointer to this type (as a reference to
    363372        either a single value or an array) (as a string).
    364373
    365         EXAMPLES:
     374        EXAMPLES::
     375
    366376            sage: from sage.ext.gen_interpreters import *
    367377            sage: ty_double.c_ptr_type()
    368378            'double*'
    … …  
    380390        same as c_decl_type; for auto-reference types, this is the
    381391        pointer type.
    382392
    383         EXAMPLES:
     393        EXAMPLES::
     394
    384395            sage: from sage.ext.gen_interpreters import *
    385396            sage: ty_double.c_local_type()
    386397            'double'
    … …  
    397408        and a Python expression, generate code to assign to the Cython
    398409        variable from the Python expression.
    399410
    400         EXAMPLES:
     411        EXAMPLES::
     412
    401413            sage: from sage.ext.gen_interpreters import *
    402414            sage: ty_double.assign_c_from_py('foo', 'bar')
    403415            u'foo = bar'
    … …  
    414426        in a wrapper class for a memory chunk with this storage type
    415427        and the given name.
    416428
    417         EXAMPLES:
     429        EXAMPLES::
     430
    418431            sage: from sage.ext.gen_interpreters import *
    419432            sage: ty_mpfr.declare_chunk_class_members('args')
    420433            u'    cdef int _n_args\n    cdef mpfr_t* _args\n'
    … …  
    430443        Returns a string allocating the memory for the class members for
    431444        a memory chunk with this storage type and the given name.
    432445
    433         EXAMPLES:
     446        EXAMPLES::
     447
    434448            sage: from sage.ext.gen_interpreters import *
    435449            sage: print ty_mpfr.alloc_chunk_data('args', 'MY_LENGTH')
    436450                    self._n_args = MY_LENGTH
    … …  
    456470        wrapper class using a memory chunk with this storage type, to
    457471        deallocate the corresponding class members.
    458472
    459         EXAMPLES:
     473        EXAMPLES::
     474
    460475            sage: from sage.ext.gen_interpreters import *
    461476            sage: print ty_double.dealloc_chunk_data('args')
    462477                    if self._args:
    … …  
    490505        as well as the properties described in the documentation for
    491506        StorageType.__init__.
    492507
    493         EXAMPLES:
     508        EXAMPLES::
     509
    494510            sage: from sage.ext.gen_interpreters import *
    495511            sage: ty_double.class_member_declarations
    496512            ''
    … …  
    516532        Since having cheap copies is essentially the definition of
    517533        StorageTypeAssignable, this always returns True.
    518534
    519         EXAMPLES:
     535        EXAMPLES::
     536
    520537            sage: from sage.ext.gen_interpreters import *
    521538            sage: ty_double.cheap_copies()
    522539            True
    … …  
    529546        r"""
    530547        Gives the C type for a single value of this type (as a string).
    531548
    532         EXAMPLES:
     549        EXAMPLES::
     550
    533551            sage: from sage.ext.gen_interpreters import *
    534552            sage: ty_double.c_decl_type()
    535553            'double'
    … …  
    545563        same as c_decl_type; for auto-reference types, this is the
    546564        pointer type.
    547565
    548         EXAMPLES:
     566        EXAMPLES::
     567
    549568            sage: from sage.ext.gen_interpreters import *
    550569            sage: ty_double.c_local_type()
    551570            'double'
    … …  
    617636        for StorageTypeAssignable.__init__.  The type is always
    618637        'PyObject*'.
    619638
    620         EXAMPLES:
     639        EXAMPLES::
     640
    621641            sage: from sage.ext.gen_interpreters import *
    622642            sage: ty_python.class_member_declarations
    623643            ''
    … …  
    637657
    638658        Returns True.
    639659
    640         EXAMPLES:
     660        EXAMPLES::
     661
    641662            sage: from sage.ext.gen_interpreters import *
    642663            sage: ty_python.python_refcounted()
    643664            True
    … …  
    648669        r"""
    649670        Gives the Cython type for a single value of this type (as a string).
    650671
    651         EXAMPLES:
     672        EXAMPLES::
     673
    652674            sage: from sage.ext.gen_interpreters import *
    653675            sage: ty_python.cython_decl_type()
    654676            'object'
    … …  
    661683        in a wrapper class for a memory chunk with this storage type
    662684        and the given name.
    663685
    664         EXAMPLES:
     686        EXAMPLES::
     687
    665688            sage: from sage.ext.gen_interpreters import *
    666689            sage: ty_python.declare_chunk_class_members('args')
    667690            u'    cdef object _list_args\n    cdef int _n_args\n    cdef PyObject** _args\n'
    … …  
    677700        Returns a string allocating the memory for the class members for
    678701        a memory chunk with this storage type and the given name.
    679702
    680         EXAMPLES:
     703        EXAMPLES::
     704
    681705            sage: from sage.ext.gen_interpreters import *
    682706            sage: print ty_python.alloc_chunk_data('args', 'MY_LENGTH')
    683707                    self._n_args = MY_LENGTH
    … …  
    700724        Our array was allocated as a Python list; this means we actually
    701725        don't need to do anything to deallocate it.
    702726
    703         EXAMPLES:
     727        EXAMPLES::
     728
    704729            sage: from sage.ext.gen_interpreters import *
    705730            sage: ty_python.dealloc_chunk_data('args')
    706731            ''
    … …  
    714739
    715740        Returns True.
    716741
    717         EXAMPLES:
     742        EXAMPLES::
     743
    718744            sage: from sage.ext.gen_interpreters import *
    719745            sage: ty_python.needs_cython_init_clear()
    720746            True
    … …  
    727753        and a Python expression, generate code to assign to the Cython
    728754        variable from the Python expression.
    729755
    730         EXAMPLES:
     756        EXAMPLES::
     757
    731758            sage: from sage.ext.gen_interpreters import *
    732759            sage: ty_python.assign_c_from_py('foo[i]', 'bar[j]')
    733760            u'foo[i] = <PyObject *>bar[j]; Py_INCREF(foo[i])'
    … …  
    740767        Generates code to initialize a variable (or array reference)
    741768        holding a PyObject*.  Sets it to NULL.
    742769
    743         EXAMPLES:
     770        EXAMPLES::
     771
    744772            sage: from sage.ext.gen_interpreters import *
    745773            sage: ty_python.cython_init('foo[i]')
    746774            u'foo[i] = NULL'
    … …  
    752780        Generates code to clear a variable (or array reference) holding
    753781        a PyObject*.
    754782
    755         EXAMPLES:
     783        EXAMPLES::
     784
    756785            sage: from sage.ext.gen_interpreters import *
    757786            sage: ty_python.cython_clear('foo[i]')
    758787            u'Py_CLEAR(foo[i])'
    … …  
    778807        respectively), as well as the properties described in
    779808        the documentation for StorageType.__init__.
    780809
    781         EXAMPLES:
     810        EXAMPLES::
     811
    782812            sage: from sage.ext.gen_interpreters import *
    783813            sage: ty_mpfr.class_member_declarations
    784814            'cdef RealField_class domain\n'
    … …  
    799829        r"""
    800830        Gives the C type for a single value of this type (as a string).
    801831
    802         EXAMPLES:
     832        EXAMPLES::
     833
    803834            sage: from sage.ext.gen_interpreters import *
    804835            sage: ty_mpfr.c_decl_type()
    805836            'mpfr_t'
    … …  
    813844        same as c_decl_type; for auto-reference types, this is the
    814845        pointer type.
    815846
    816         EXAMPLES:
     847        EXAMPLES::
     848
    817849            sage: from sage.ext.gen_interpreters import *
    818850            sage: ty_mpfr.c_local_type()
    819851            'mpfr_ptr'
    … …  
    828860        All known examples of auto-reference types do need a special
    829861        initialization call, so this always returns True.
    830862
    831         EXAMPLES:
     863        EXAMPLES::
     864
    832865            sage: from sage.ext.gen_interpreters import *
    833866            sage: ty_mpfr.needs_cython_init_clear()
    834867            True
    … …  
    860893        variable names that don't conflict.  (The id system has
    861894        never actually been used, so bugs probably remain.)
    862895
    863         EXAMPLES:
     896        EXAMPLES::
     897
    864898            sage: from sage.ext.gen_interpreters import *
    865899            sage: ty_mpfr.class_member_declarations
    866900            'cdef RealField_class domain\n'
    … …  
    873907            sage: ty_mpfr.ref_type
    874908            'mpfr_ptr'
    875909
    876         TESTS:
     910        TESTS::
     911
    877912            sage: ty_mpfr2 = StorageTypeMPFR(id='_the_second')
    878913            sage: ty_mpfr2.class_member_declarations
    879914            'cdef RealField_class domain_the_second\n'
    … …  
    894929        Generates code to initialize an mpfr_t reference (a variable, an
    895930        array reference, etc.)
    896931
    897         EXAMPLES:
     932        EXAMPLES::
     933
    898934            sage: from sage.ext.gen_interpreters import *
    899935            sage: ty_mpfr.cython_init('foo[i]')
    900936            u'mpfr_init2(foo[i], self.domain.prec())'
    … …  
    907943        Generates code to clear an mpfr_t reference (a variable, an
    908944        array reference, etc.)
    909945
    910         EXAMPLES:
     946        EXAMPLES::
     947
    911948            sage: from sage.ext.gen_interpreters import *
    912949            sage: ty_mpfr.cython_clear('foo[i]')
    913950            'mpfr_clear(foo[i])'
    … …  
    920957        and a Python expression, generate code to assign to the Cython
    921958        variable from the Python expression.
    922959
    923         EXAMPLES:
     960        EXAMPLES::
     961
    924962            sage: from sage.ext.gen_interpreters import *
    925963            sage: ty_mpfr.assign_c_from_py('foo[i]', 'bar[j]')
    926964            u'rn = self.domain(bar[j])\nmpfr_set(foo[i], rn.value, GMP_RNDN)'
    … …  
    961999        used in generated variable names, etc.) and "storage_type",
    9621000        which is a StorageType object.
    9631001
    964         EXAMPLES:
     1002        EXAMPLES::
     1003
    9651004            sage: from sage.ext.gen_interpreters import *
    9661005            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    9671006            sage: mc.name
    … …  
    9761015        r"""
    9771016        Give a string representation of this memory chunk.
    9781017
    979         EXAMPLES:
     1018        EXAMPLES::
     1019
    9801020            sage: from sage.ext.gen_interpreters import *
    9811021            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    9821022            sage: mc
    … …  
    9911031        Returns a string giving the declarations of the class members
    9921032        in a wrapper class for this memory chunk.
    9931033
    994         EXAMPLES:
     1034        EXAMPLES::
     1035
    9951036            sage: from sage.ext.gen_interpreters import *
    9961037            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    9971038            sage: mc.declare_class_members()
    … …  
    10051046        class using this memory chunk, to initialize the corresponding
    10061047        class members.
    10071048
    1008         EXAMPLES:
     1049        EXAMPLES::
     1050
    10091051            sage: from sage.ext.gen_interpreters import *
    10101052            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    10111053            sage: print mc.init_class_members()
    … …  
    10251067        class using this memory chunk, to deallocate the corresponding
    10261068        class members.
    10271069
    1028         EXAMPLES:
     1070        EXAMPLES::
     1071
    10291072            sage: from sage.ext.gen_interpreters import *
    10301073            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    10311074            sage: print mc.dealloc_class_members()
    … …  
    10421085        Returns the string to use to declare the interpreter parameter
    10431086        corresponding to this memory chunk.
    10441087
    1045         EXAMPLES:
     1088        EXAMPLES::
     1089
    10461090            sage: from sage.ext.gen_interpreters import *
    10471091            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    10481092            sage: mc.declare_parameter()
    … …  
    10551099        Returns a string to put in the __call__ method of a wrapper
    10561100        class using this memory chunk, to allocate local variables.
    10571101       
    1058         EXAMPLES:
     1102        EXAMPLES::
     1103
    10591104            sage: from sage.ext.gen_interpreters import *
    10601105            sage: mc = MemoryChunkRRRetval('retval', ty_mpfr)
    10611106            sage: mc.declare_call_locals()
    … …  
    10681113        Returns the string to pass the argument corresponding to this
    10691114        memory chunk to the interpreter.
    10701115
    1071         EXAMPLES:
     1116        EXAMPLES::
     1117
    10721118            sage: from sage.ext.gen_interpreters import *
    10731119            sage: mc = MemoryChunkConstants('constants', ty_mpfr)
    10741120            sage: mc.pass_argument()
    … …  
    10821128        memory chunk to the interpreter, for use in the call_c method.
    10831129        Almost always the same as pass_argument.
    10841130
    1085         EXAMPLES:
     1131        EXAMPLES::
     1132
    10861133            sage: from sage.ext.gen_interpreters import *
    10871134            sage: mc = MemoryChunkConstants('constants', ty_mpfr)
    10881135            sage: mc.pass_call_c_argument()
    … …  
    11011148        This method returns True if this memory chunk is modified by the
    11021149        interpreter and needs some sort of cleanup when an error happens.
    11031150
    1104         EXAMPLES:
     1151        EXAMPLES::
     1152
    11051153            sage: from sage.ext.gen_interpreters import *
    11061154            sage: mc = MemoryChunkConstants('constants', ty_mpfr)
    11071155            sage: mc.needs_cleanup_on_error()
    … …  
    11231171                ... hardcoded non-stack code
    11241172        but that hasn't been done yet.
    11251173
    1126         EXAMPLES:
     1174        EXAMPLES::
     1175
    11271176            sage: from sage.ext.gen_interpreters import *
    11281177            sage: mc = MemoryChunkScratch('scratch', ty_mpfr)
    11291178            sage: mc.is_stack()
    … …  
    11441193        INCREF/DECREF and didn't have to explicitly test
    11451194        is_python_refcounted_stack.
    11461195
    1147         EXAMPLES:
     1196        EXAMPLES::
     1197
    11481198            sage: from sage.ext.gen_interpreters import *
    11491199            sage: mc = MemoryChunkScratch('args', ty_python)
    11501200            sage: mc.is_python_refcounted_stack()
    … …  
    11711221        class using this memory chunk, to initialize the corresponding
    11721222        class members.
    11731223
    1174         EXAMPLES:
     1224        EXAMPLES::
     1225
    11751226            sage: from sage.ext.gen_interpreters import *
    11761227            sage: mc = MemoryChunkArguments('args', ty_double)
    11771228            sage: print mc.init_class_members()
    … …  
    11921243        class using this memory chunk, to deallocate the corresponding
    11931244        class members.
    11941245
    1195         EXAMPLES:
     1246        EXAMPLES::
     1247
    11961248            sage: from sage.ext.gen_interpreters import *
    11971249            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    11981250            sage: print mc.dealloc_class_members()
    … …  
    12091261        Returns the string to pass the argument corresponding to this
    12101262        memory chunk to the interpreter.
    12111263
    1212         EXAMPLES:
     1264        EXAMPLES::
     1265
    12131266            sage: from sage.ext.gen_interpreters import *
    12141267            sage: mc = MemoryChunkConstants('constants', ty_mpfr)
    12151268            sage: mc.pass_argument()
    … …  
    12311284        class using this memory chunk, to initialize the corresponding
    12321285        class members.
    12331286
    1234         EXAMPLES:
     1287        EXAMPLES::
     1288
    12351289            sage: from sage.ext.gen_interpreters import *
    12361290            sage: mc = MemoryChunkConstants('constants', ty_mpfr)
    12371291            sage: print mc.init_class_members()
    … …  
    12681322        Handle the arguments of __call__ -- copy them into a pre-allocated
    12691323        array, ready to pass to the interpreter.
    12701324
    1271         EXAMPLES:
     1325        EXAMPLES::
     1326
    12721327            sage: from sage.ext.gen_interpreters import *
    12731328            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    12741329            sage: print mc.setup_args()
    … …  
    12911346        Returns the string to pass the argument corresponding to this
    12921347        memory chunk to the interpreter.
    12931348
    1294         EXAMPLES:
     1349        EXAMPLES::
     1350
    12951351            sage: from sage.ext.gen_interpreters import *
    12961352            sage: mc = MemoryChunkArguments('args', ty_mpfr)
    12971353            sage: mc.pass_argument()
    … …  
    13161372        the properties described in the documentation for
    13171373        MemoryChunk.__init__.
    13181374
    1319         EXAMPLES:
     1375        EXAMPLES::
     1376
    13201377            sage: from sage.ext.gen_interpreters import *
    13211378            sage: mc = MemoryChunkScratch('stack', ty_double, is_stack=True)
    13221379            sage: mc.name
    … …  
    13341391        Says whether this memory chunk is a stack.  This affects code
    13351392        generation for instructions using this memory chunk.
    13361393
    1337         EXAMPLES:
     1394        EXAMPLES::
     1395
    13381396            sage: from sage.ext.gen_interpreters import *
    13391397            sage: mc = MemoryChunkScratch('stack', ty_mpfr, is_stack=True)
    13401398            sage: mc.is_stack()
    … …  
    13531411        This method returns True if this memory chunk is modified by the
    13541412        interpreter and needs some sort of cleanup when an error happens.
    13551413
    1356         EXAMPLES:
     1414        EXAMPLES::
     1415
    13571416            sage: from sage.ext.gen_interpreters import *
    13581417            sage: mc = MemoryChunkScratch('registers', ty_python)
    13591418            sage: mc.needs_cleanup_on_error()
    … …  
    13711430        have left values in the chunk, so we need to go through
    13721431        the chunk and Py_CLEAR it.
    13731432
    1374         EXAMPLES:
     1433        EXAMPLES::
     1434
    13751435            sage: from sage.ext.gen_interpreters import *
    13761436            sage: mc = MemoryChunkScratch('registers', ty_python)
    13771437            sage: print mc.handle_cleanup()
    … …  
    13971457        Returns a string giving the declarations of the class members
    13981458        in a wrapper class for this memory chunk.
    13991459
    1400         EXAMPLES:
     1460        EXAMPLES::
     1461
    14011462            sage: from sage.ext.gen_interpreters import *
    14021463            sage: mc = MemoryChunkRRRetval('retval', ty_mpfr)
    14031464            sage: mc.declare_class_members()
    … …  
    14101471        Returns a string to put in the __call__ method of a wrapper
    14111472        class using this memory chunk, to allocate local variables.
    14121473       
    1413         EXAMPLES:
     1474        EXAMPLES::
     1475
    14141476            sage: from sage.ext.gen_interpreters import *
    14151477            sage: mc = MemoryChunkRRRetval('retval', ty_mpfr)
    14161478            sage: mc.declare_call_locals()
    … …  
    14251487        Returns the string to pass the argument corresponding to this
    14261488        memory chunk to the interpreter.
    14271489
    1428         EXAMPLES:
     1490        EXAMPLES::
     1491
    14291492            sage: from sage.ext.gen_interpreters import *
    14301493            sage: mc = MemoryChunkRRRetval('retval', ty_mpfr)
    14311494            sage: mc.pass_argument()
    … …  
    14381501        Returns the string to pass the argument corresponding to this
    14391502        memory chunk to the interpreter, for use in the call_c method.
    14401503
    1441         EXAMPLES:
     1504        EXAMPLES::
     1505
    14421506            sage: from sage.ext.gen_interpreters import *
    14431507            sage: mc = MemoryChunkRRRetval('retval', ty_mpfr)
    14441508            sage: mc.pass_call_c_argument()
    … …  
    14591523        Returns a string giving the declarations of the class members
    14601524        in a wrapper class for this memory chunk.
    14611525
    1462         EXAMPLES:
     1526        EXAMPLES::
     1527
    14631528            sage: from sage.ext.gen_interpreters import *
    14641529            sage: mc = MemoryChunkPythonArguments('args', ty_python)
    14651530        """
    … …  
    14711536        class using this memory chunk, to initialize the corresponding
    14721537        class members.
    14731538
    1474         EXAMPLES:
     1539        EXAMPLES::
     1540
    14751541            sage: from sage.ext.gen_interpreters import *
    14761542            sage: mc = MemoryChunkPythonArguments('args', ty_python)
    14771543            sage: mc.init_class_members()
    … …  
    14861552        r"""
    14871553        Handle the arguments of __call__.  Nothing to do.
    14881554
    1489         EXAMPLES:
     1555        EXAMPLES::
     1556
    14901557            sage: from sage.ext.gen_interpreters import *
    14911558            sage: mc = MemoryChunkPythonArguments('args', ty_python)
    14921559            sage: mc.setup_args()
    … …  
    14981565        r"""
    14991566        Pass the innards of the argument tuple to the interpreter.
    15001567
    1501         EXAMPLES:
     1568        EXAMPLES::
     1569
    15021570            sage: from sage.ext.gen_interpreters import *
    15031571            sage: mc = MemoryChunkPythonArguments('args', ty_python)
    15041572            sage: mc.pass_argument()
    … …  
    15241592        Handle the arguments of __call__.  Note: This hardcodes
    15251593        "self._domain".
    15261594
    1527         EXAMPLES:
     1595        EXAMPLES::
     1596
    15281597            sage: from sage.ext.gen_interpreters import *
    15291598            sage: mc = MemoryChunkElementArguments('args', ty_python)
    15301599            sage: mc.setup_args()
    … …  
    15361605        r"""
    15371606        Pass the innards of the argument tuple to the interpreter.
    15381607
    1539         EXAMPLES:
     1608        EXAMPLES::
     1609
    15401610            sage: from sage.ext.gen_interpreters import *
    15411611            sage: mc = MemoryChunkElementArguments('args', ty_python)
    15421612            sage: mc.pass_argument()
    … …  
    15561626
    15571627        Always uses the type ty_python.
    15581628
    1559         EXAMPLES:
     1629        EXAMPLES::
     1630
    15601631            sage: from sage.ext.gen_interpreters import *
    15611632            sage: mc = MemoryChunkPyConstant('domain')
    15621633            sage: mc.name
    … …  
    15711642        Returns a string giving the declarations of the class members
    15721643        in a wrapper class for this memory chunk.
    15731644
    1574         EXAMPLES:
     1645        EXAMPLES::
     1646
    15751647            sage: from sage.ext.gen_interpreters import *
    15761648            sage: mc = MemoryChunkPyConstant('domain')
    15771649            sage: mc.declare_class_members()
    … …  
    15871659        class using this memory chunk, to initialize the corresponding
    15881660        class members.
    15891661
    1590         EXAMPLES:
     1662        EXAMPLES::
     1663
    15911664            sage: from sage.ext.gen_interpreters import *
    15921665            sage: mc = MemoryChunkPyConstant('domain')
    15931666            sage: mc.init_class_members()
    … …  
    16021675        Returns the string to use to declare the interpreter parameter
    16031676        corresponding to this memory chunk.
    16041677
    1605         EXAMPLES:
     1678        EXAMPLES::
     1679
    16061680            sage: from sage.ext.gen_interpreters import *
    16071681            sage: mc = MemoryChunkPyConstant('domain')
    16081682            sage: mc.declare_parameter()
    … …  
    16151689        Returns the string to pass the argument corresponding to this
    16161690        memory chunk to the interpreter.
    16171691
    1618         EXAMPLES:
     1692        EXAMPLES::
     1693
    16191694            sage: from sage.ext.gen_interpreters import *
    16201695            sage: mc = MemoryChunkPyConstant('domain')
    16211696            sage: mc.pass_argument()
    … …  
    16591734    for a number n (meaning to use that many arguments), or '@C', where
    16601735    C is the code chunk.
    16611736
    1662     EXAMPLES:
     1737    EXAMPLES::
     1738
    16631739        sage: from sage.ext.gen_interpreters import *
    16641740        sage: mc_stack = MemoryChunkScratch('stack', ty_double, is_stack=True)
    16651741        sage: mc_args = MemoryChunkArguments('args', ty_double)
    … …  
    17291805    address or length.  (See the docstring for params_gen for more
    17301806    information on parameter specifications.)
    17311807
    1732     EXAMPLES:
     1808    EXAMPLES::
     1809
    17331810        sage: from sage.ext.gen_interpreters import *
    17341811        sage: mc_code = MemoryChunkConstants('code', ty_int)
    17351812        sage: string_of_addr(mc_code)
    … …  
    18071884    rules are described in the docstring of the PythonInterpreter
    18081885    class.
    18091886
    1810     EXAMPLES:
     1887    EXAMPLES::
     1888
    18111889        sage: from sage.ext.gen_interpreters import *
    18121890        sage: pg = RDFInterpreter().pg
    18131891        sage: InstrSpec('add', pg('SS','S'), code='o0 = i0+i1;')
    … …  
    18301908                                  objects and includes its own
    18311909                                  reference-counting
    18321910
    1833         EXAMPLES:
     1911        EXAMPLES::
     1912
    18341913            sage: from sage.ext.gen_interpreters import *
    18351914           
    18361915            sage: pg = RDFInterpreter().pg
    … …  
    19041983        of its name, a brief stack specification, and its code
    19051984        (possibly abbreviated).
    19061985
    1907         EXAMPLES:
     1986        EXAMPLES::
     1987
    19081988            sage: from sage.ext.gen_interpreters import *
    19091989            sage: pg = RDFInterpreter().pg
    19101990            sage: InstrSpec('add', pg('SS','S'), code='o0 = i0+i1;')
    … …  
    19242004    A helper function for creating instructions implemented by
    19252005    a single infix binary operator.
    19262006
    1927     EXAMPLES:
     2007    EXAMPLES::
     2008
    19282009        sage: from sage.ext.gen_interpreters import *
    19292010        sage: pg = RDFInterpreter().pg
    19302011        sage: instr_infix('mul', pg('SS', 'S'), '*')
    … …  
    19372018    A helper function for creating instructions implemented by
    19382019    a two-argument function call.
    19392020
    1940     EXAMPLES:
     2021    EXAMPLES::
     2022
    19412023        sage: from sage.ext.gen_interpreters import *
    19422024        sage: pg = RDFInterpreter().pg
    19432025        sage: instr_funcall_2args('atan2', pg('SS', 'S'), 'atan2')
    … …  
    19502032    A helper function for creating instructions with one input
    19512033    and one output.
    19522034
    1953     EXAMPLES:
     2035    EXAMPLES::
     2036
    19542037        sage: from sage.ext.gen_interpreters import *
    19552038        sage: pg = RDFInterpreter().pg
    19562039        sage: instr_unary('sin', pg('S','S'), 'sin(i0)')
    … …  
    19652048    A helper function for creating MPFR instructions with two inputs
    19662049    and one output.
    19672050
    1968     EXAMPLES:
     2051    EXAMPLES::
     2052
    19692053        sage: from sage.ext.gen_interpreters import *
    19702054        sage: pg = RRInterpreter().pg
    19712055        sage: instr_funcall_2args_mpfr('add', pg('SS','S'), 'mpfr_add')
    … …  
    19782062    A helper function for creating MPFR instructions with one input
    19792063    and one output.
    19802064
    1981     EXAMPLES:
     2065    EXAMPLES::
     2066
    19822067        sage: from sage.ext.gen_interpreters import *
    19832068        sage: pg = RRInterpreter().pg
    19842069        sage: instr_funcall_1arg_mpfr('exp', pg('S','S'), 'mpfr_exp')
    … …  
    19982083
    19992084        Initializes the following fields:
    20002085
    2001         header -- a code snippet to go at the top of the C interpreter
     2086        h_header -- a code snippet to go at the top of the C interpreter
     2087                  header file
     2088
     2089        c_header -- a code snippet to go at the top of the C interpreter
    20022090                  source file
    2003         pxd_header -- a code snippet to go at the top of the wrapper 
     2091        pxd_header -- a code snippet to go at the top of the wrapper
    20042092                      class .pxd file
    2005         pyx_header -- a code snippet to go at the top of the wrapper 
     2093        pyx_header -- a code snippet to go at the top of the wrapper
    20062094                      class source file
    20072095        err_return -- a string indicating the value to be returned
    20082096                      in case of a Python exception
    … …  
    20112099                               don't correspond to memory chunks
    20122100        extra_members_initialize -- Code to initialize extra_class_members
    20132101
    2014         EXAMPLES:
     2102        EXAMPLES::
     2103
    20152104            sage: from sage.ext.gen_interpreters import *
    20162105            sage: interp = RDFInterpreter()
    2017             sage: interp.header
     2106            sage: interp.h_header
    20182107            '\n#include <gsl/gsl_math.h>\n'
     2108            sage: interp.c_header
     2109            ''
    20192110            sage: interp.pxd_header
    20202111            ''
    20212112            sage: interp.pyx_header
    … …  
    20302121            sage: interp.extra_members_initialize
    20312122            ''
    20322123        """
    2033         self.header = ''
     2124        self.h_header = ''
     2125        self.c_header = ''
    20342126        self.pxd_header = ''
    20352127        self.pyx_header = ''
    20362128        self.err_return = 'NULL'
    … …  
    20452137        Must be called at the end of __init__ by any subclass of
    20462138        InterpreterSpec.
    20472139
    2048         EXAMPLES:
     2140        EXAMPLES::
     2141
    20492142            sage: from sage.ext.gen_interpreters import *
    20502143            sage: interp = RDFInterpreter()
    20512144            sage: interp.instr_descs[5].opcode
    … …  
    20872180                            method (that bypasses the Python call overhead)
    20882181                            (default True)
    20892182
    2090         EXAMPLES:
     2183        EXAMPLES::
     2184
    20912185            sage: from sage.ext.gen_interpreters import *
    20922186            sage: rdf = RDFInterpreter()
    20932187            sage: rr = RRInterpreter()
    … …  
    21352229        r"""
    21362230        Initialize an RDFInterpreter.
    21372231
    2138         EXAMPLES:
     2232        EXAMPLES::
     2233
    21392234            sage: from sage.ext.gen_interpreters import *
    21402235            sage: interp = RDFInterpreter()
    21412236            sage: interp.name
    … …  
    21872282        pg = params_gen(A=self.mc_args, C=self.mc_constants, D=self.mc_code,
    21882283                        S=self.mc_stack, P=self.mc_py_constants)
    21892284        self.pg = pg
    2190         self.header = """
     2285        self.h_header = """
    21912286#include <gsl/gsl_math.h>
    21922287"""
    21932288        instrs = [
    … …  
    22652360        r"""
    22662361        Initialize a CDFInterpreter.
    22672362
    2268         EXAMPLES:
     2363        EXAMPLES::
     2364
    22692365            sage: from sage.ext.gen_interpreters import *
    22702366            sage: interp = CDFInterpreter()
    22712367            sage: interp.name
    … …  
    22972393        pg = params_gen(A=self.mc_args, C=self.mc_constants, D=self.mc_code,
    22982394                        S=self.mc_stack, P=self.mc_py_constants)
    22992395        self.pg = pg
    2300         self.header = """
     2396        self.h_header = """
    23012397#include <stdlib.h>
    23022398#include <complex.h>
    23032399
    23042400typedef double complex double_complex;
    23052401
    23062402extern int cdf_py_call_helper(PyObject*, int, double complex*, double complex*);
    2307 
    23082403"""
    23092404        self.pxd_header = """
    23102405# This is to work around a header ordering bug in Cython < 0.11
    … …  
    24022497        r"""
    24032498        Initialize an RDFInterpreter.
    24042499
    2405         EXAMPLES:
     2500        EXAMPLES::
     2501
    24062502            sage: from sage.ext.gen_interpreters import *
    24072503            sage: interp = RRInterpreter()
    24082504            sage: interp.name
    … …  
    24212517
    24222518        That py_call instruction is particularly interesting, and
    24232519        demonstrates a useful technique to let you use Cython code
    2424         in an interpreter.  Let's look more closely:
     2520        in an interpreter.  Let's look more closely::
    24252521
    24262522            sage: print instrs['py_call'].code
    24272523            if (!rr_py_call_helper(domain, i0, n_i1, i1, o0)) {
    … …  
    24292525            }
    24302526
    24312527        This instruction makes use of the function rr_py_call_helper,
    2432         which is declared...
    2433 
    2434             sage: print interp.header
     2528        which is declared::
     2529
     2530            sage: print interp.h_header
     2531            <BLANKLINE>
    24352532            #include <mpfr.h>
     2533            <BLANKLINE>
    24362534            extern int rr_py_call_helper(PyObject*, PyObject*, int, mpfr_t*, mpfr_t*);
    24372535
    2438         In particular, rr_py_call_helper comes from:
    2439            
     2536        In particular, rr_py_call_helper comes from::
     2537
    24402538            sage: print interp.pyx_header
    24412539            cdef public bint rr_py_call_helper(object domain, object fn,
    24422540                                               int n_args,
    … …  
    24692567                        S=self.mc_stack,
    24702568                        P=self.mc_py_constants)
    24712569        self.pg = pg
    2472         self.header = """
     2570        self.h_header = """
    24732571#include <mpfr.h>
     2572
    24742573extern int rr_py_call_helper(PyObject*, PyObject*, int, mpfr_t*, mpfr_t*);
    2475 """.strip()
    2476 
     2574"""
    24772575        self.pxd_header = """
    24782576from sage.rings.real_mpfr cimport RealField_class, RealNumber
    24792577from sage.libs.mpfr cimport *
    … …  
    25722670        r"""
    25732671        Initialize a PythonInterpreter.
    25742672
    2575         EXAMPLES:
     2673        EXAMPLES::
     2674
    25762675            sage: from sage.ext.gen_interpreters import *
    25772676            sage: interp = PythonInterpreter()
    25782677            sage: interp.name
    … …  
    25982697        pg = params_gen(A=self.mc_args, C=self.mc_constants, D=self.mc_code,
    25992698                        S=self.mc_stack)
    26002699        self.pg = pg
    2601         self.header = """
    2602 #include <Python.h>
     2700        self.h_header = """
    26032701#define CHECK(x) (x != NULL)
    26042702"""
    26052703        instrs = [
    … …  
    26642762        r"""
    26652763        Initialize an ElementInterpreter.
    26662764
    2667         EXAMPLES:
     2765        EXAMPLES::
     2766
    26682767            sage: from sage.ext.gen_interpreters import *
    26692768            sage: interp = ElementInterpreter()
    26702769            sage: interp.name
    … …  
    26882787        self.mc_domain_info = MemoryChunkPyConstant('domain')
    26892788        self.chunks = [self.mc_args, self.mc_constants, self.mc_stack,
    26902789                       self.mc_domain_info, self.mc_code]
    2691         self.header = """
    2692 #include <Python.h>
    2693 
     2790        self.h_header = """
    26942791extern PyObject* el_check_element(PyObject*, PyObject*);
    26952792
    26962793#define CHECK(x) do_check(&(x), domain)
    … …  
    27352832        INPUTS:
    27362833            spec -- an InterpreterSpec
    27372834
    2738         EXAMPLES:
     2835        EXAMPLES::
     2836
    27392837            sage: from sage.ext.gen_interpreters import *
    27402838            sage: interp = RDFInterpreter()
    27412839            sage: gen = InterpreterGenerator(interp)
    … …  
    27632861        See the documentation for the get_interpreter method for more
    27642862        information.
    27652863
    2766         EXAMPLES:
     2864        EXAMPLES::
     2865
    27672866            sage: from sage.ext.gen_interpreters import *
    27682867            sage: interp = RDFInterpreter()
    27692868            sage: gen = InterpreterGenerator(interp)
    … …  
    29093008        wrapper) or the definition (in the C interpreter) of the interpreter
    29103009        function.
    29113010
    2912         EXAMPLES:
     3011        EXAMPLES::
     3012
    29133013            sage: from sage.ext.gen_interpreters import *
    29143014            sage: interp = ElementInterpreter()
    29153015            sage: gen = InterpreterGenerator(interp)
    … …  
    29383038        {% endif %}{{ ch.declare_parameter() }}
    29393039{%- endfor %})""", ret_ty=ret_ty, s=s)
    29403040
     3041    def write_interpreter_header(self, write):
     3042        r"""
     3043        Generate the header code for the C interpreter.
     3044
     3045        EXAMPLES::
     3046
     3047            sage: from sage.ext.gen_interpreters import *
     3048            sage: interp = RDFInterpreter()
     3049            sage: gen = InterpreterGenerator(interp)
     3050            sage: import cStringIO
     3051            sage: buff = cStringIO.StringIO()
     3052            sage: gen.write_interpreter_header(buff.write)
     3053            sage: print buff.getvalue()
     3054            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */ ...
     3055        """
     3056        s = self._spec
     3057        w = write
     3058        w(je("""
     3059/* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
     3060#include <Python.h>
     3061{% print s.h_header %}
     3062
     3063{{ myself.func_header() }};
     3064""", s=s, i=indent_lines, myself=self))
     3065
    29413066    def write_interpreter(self, write):
    29423067        r"""
    29433068        Generate the code for the C interpreter.
    … …  
    29493074        See the documentation for the get_interpreter method for more
    29503075        information.
    29513076
    2952         EXAMPLES:
     3077        EXAMPLES::
     3078
    29533079            sage: from sage.ext.gen_interpreters import *
    29543080            sage: interp = RDFInterpreter()
    29553081            sage: gen = InterpreterGenerator(interp)
    … …  
    29633089        w = write
    29643090        w(je("""
    29653091/* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
    2966 #include <Python.h>
    2967 {% print s.header %}
     3092#include "interp_{{ s.name }}.h"
     3093{% print s.c_header %}
     3094
    29683095{{ myself.func_header() }} {
    29693096  while (1) {
    29703097    switch (*code++) {
    … …  
    29923119        See the documentation for the get_wrapper method for more
    29933120        information.
    29943121
    2995         EXAMPLES:
     3122        EXAMPLES::
     3123
    29963124            sage: from sage.ext.gen_interpreters import *
    29973125            sage: interp = RDFInterpreter()
    29983126            sage: gen = InterpreterGenerator(interp)
    … …  
    30573185from sage.ext.fast_callable cimport Wrapper
    30583186{% print s.pyx_header %}
    30593187
    3060 cdef extern {{ myself.func_header(cython=true) -}}
     3188cdef extern from "interp_{{ s.name }}.h":
     3189    {{ myself.func_header(cython=true) -}}
    30613190{% if s.err_return != 'NULL' %}
    3062  except? {{ s.err_return -}}
     3191 except? {{ s.err_return }}
    30633192{% endif %}
    30643193
    30653194cdef class Wrapper_{{ s.name }}(Wrapper):
    … …  
    31563285        See the documentation for the get_pxd method for more
    31573286        information.
    31583287
    3159         EXAMPLES:
     3288        EXAMPLES::
     3289
    31603290            sage: from sage.ext.gen_interpreters import *
    31613291            sage: interp = RDFInterpreter()
    31623292            sage: gen = InterpreterGenerator(interp)
    … …  
    31993329{% endif %}
    32003330""", s=s, myself=self, types=types, indent_lines=indent_lines, arg_ch=arg_ch))
    32013331
     3332    def get_interpreter_header(self):
     3333        r"""
     3334        Returns the header code for the C interpreter.
     3335
     3336        EXAMPLES:
     3337
     3338        First we get the InterpreterSpec for several interpreters::
     3339
     3340            sage: from sage.ext.gen_interpreters import *
     3341            sage: rdf_spec = RDFInterpreter()
     3342            sage: rr_spec = RRInterpreter()
     3343            sage: cdf_spec = CDFInterpreter()
     3344            sage: el_spec = ElementInterpreter()
     3345
     3346        Then we get the actual interpreter code::
     3347
     3348            sage: rdf_interp_h = InterpreterGenerator(rdf_spec).get_interpreter_header()
     3349            sage: rr_interp_h = InterpreterGenerator(rr_spec).get_interpreter_header()
     3350            sage: cdf_interp_h = InterpreterGenerator(cdf_spec).get_interpreter_header()
     3351            sage: el_interp_h = InterpreterGenerator(el_spec).get_interpreter_header()
     3352
     3353        Each interpreter starts with a file header; this can be
     3354        customized on a per-interpreter basis::
     3355
     3356            sage: print rdf_interp_h
     3357            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
     3358            #include <Python.h>
     3359            <BLANKLINE>
     3360            #include <gsl/gsl_math.h>
     3361            ...
     3362            sage: print rr_interp_h
     3363            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
     3364            #include <Python.h>
     3365            <BLANKLINE>
     3366            #include <mpfr.h>
     3367            ...
     3368            sage: print cdf_interp_h
     3369            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
     3370            #include <Python.h>
     3371            <BLANKLINE>
     3372            #include <stdlib.h>
     3373            #include <complex.h>
     3374            ...
     3375            sage: print el_interp_h
     3376            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
     3377            #include <Python.h>
     3378            <BLANKLINE>
     3379            extern PyObject* el_check_element(PyObject*, PyObject*);
     3380            <BLANKLINE>
     3381            #define CHECK(x) do_check(&(x), domain)
     3382            ...
     3383        """
     3384        import cStringIO
     3385        buff = cStringIO.StringIO()
     3386        self.write_interpreter_header(buff.write)
     3387        return buff.getvalue()
     3388
    32023389    def get_interpreter(self):
    32033390        r"""
    32043391        Returns the code for the C interpreter.
    32053392
    32063393        EXAMPLES:
    32073394
    3208         First we get the InterpreterSpec for several interpreters:
     3395        First we get the InterpreterSpec for several interpreters::
     3396
    32093397            sage: from sage.ext.gen_interpreters import *
    32103398            sage: rdf_spec = RDFInterpreter()
    32113399            sage: rr_spec = RRInterpreter()
    32123400            sage: el_spec = ElementInterpreter()
    32133401
    3214         Then we get the actual interpreter code:
     3402        Then we get the actual interpreter code::
     3403
    32153404            sage: rdf_interp = InterpreterGenerator(rdf_spec).get_interpreter()
    32163405            sage: rr_interp = InterpreterGenerator(rr_spec).get_interpreter()
    32173406            sage: el_interp = InterpreterGenerator(el_spec).get_interpreter()
    … …  
    32193408        Now we can look through these interpreters.
    32203409
    32213410        Each interpreter starts with a file header; this can be
    3222         customized on a per-interpreter basis:
     3411        customized on a per-interpreter basis::
     3412
    32233413            sage: print rr_interp
    32243414            /* Automatically generated by ext/gen_interpreters.py.  Do not edit! */
    3225             #include <Python.h>
    3226             #include <mpfr.h>
     3415            #include "interp_rr.h"
    32273416            ...
    32283417
    32293418        Next is the function header, with one argument per memory chunk
    3230         in the interpreter spec.
     3419        in the interpreter spec::
     3420
    32313421            sage: print el_interp
    32323422            /* ... */ ...
    32333423            PyObject* interp_el(PyObject** args,
    … …  
    32393429
    32403430        Currently, the interpreters have a very simple structure; just
    32413431        grab the next instruction and execute it, in a switch
    3242         statement.
     3432        statement::
     3433
    32433434            sage: print rdf_interp
    32443435            /* ... */ ...
    32453436              while (1) {
    … …  
    32473438            ...
    32483439
    32493440        Then comes the code for each instruction.  Here is one of the
    3250         simplest instructions:
     3441        simplest instructions::
     3442
    32513443            sage: print rdf_interp
    32523444            /* ... */ ...
    32533445                case 10: /* neg */
    … …  
    32653457
    32663458        Let's look at the MPFR-based version of this instruction.
    32673459        This is an example of an interpreter with an auto-reference
    3268         type.
     3460        type::
     3461
    32693462            sage: print rr_interp
    32703463            /* ... */ ...
    32713464                case 10: /* neg */
    … …  
    32843477        mpfr_t variables.
    32853478
    32863479        For completeness, let's look at this instruction in the
    3287         Python-object element interpreter.
     3480        Python-object element interpreter::
     3481
    32883482            sage: print el_interp
    32893483            /* ... */ ...
    32903484                case 10: /* neg */
    … …  
    33213515
    33223516        EXAMPLES:
    33233517
    3324         First we get the InterpreterSpec for several interpreters:
     3518        First we get the InterpreterSpec for several interpreters::
     3519
    33253520            sage: from sage.ext.gen_interpreters import *
    33263521            sage: rdf_spec = RDFInterpreter()
    33273522            sage: rr_spec = RRInterpreter()
    33283523            sage: el_spec = ElementInterpreter()
    33293524
    3330         Then we get the actual wrapper code:
     3525        Then we get the actual wrapper code::
     3526
    33313527            sage: rdf_wrapper = InterpreterGenerator(rdf_spec).get_wrapper()
    33323528            sage: rr_wrapper = InterpreterGenerator(rr_spec).get_wrapper()
    33333529            sage: el_wrapper = InterpreterGenerator(el_spec).get_wrapper()
    … …  
    33363532
    33373533        Each wrapper starts with a file header; this can be
    33383534        customized on a per-interpreter basis (some blank lines have been
    3339         elided below):
     3535        elided below)::
     3536
    33403537            sage: print rdf_wrapper
    33413538            # Automatically generated by ext/gen_interpreters.py.  Do not edit!
    33423539            include "../stdsage.pxi"
    … …  
    33553552            from sage.ext.fast_callable cimport Wrapper
    33563553            ...
    33573554
    3358         Next is the declaration of the C interpreter function.
     3555        Next is the declaration of the C interpreter function::
     3556
    33593557            sage: print rdf_wrapper
    33603558            # ...
    3361             cdef extern double interp_rdf(double* args,
     3559            cdef extern from "interp_rdf.h":
     3560                double interp_rdf(double* args,
    33623561                    double* constants,
    33633562                    PyObject** py_constants,
    33643563                    double* stack,
    … …  
    33753574
    33763575        Next comes the actual wrapper class.  The member declarations
    33773576        are in the corresponding pxd file; see the documentation for
    3378         get_pxd to see them.
     3577        get_pxd to see them::
     3578
    33793579            sage: print rdf_wrapper
    33803580            # ...
    33813581            cdef class Wrapper_rdf(Wrapper):
    33823582                # attributes are declared in corresponding .pxd file
    33833583            ...
    33843584
    3385         Next is the __init__ method, which starts like this:
     3585        Next is the __init__ method, which starts like this::
     3586
    33863587            sage: print rdf_wrapper
    33873588            # ...
    33883589                def __init__(self, args):
    … …  
    34123613
    34133614        Basically the same code is repeated, with minor variations, for
    34143615        each memory chunk; for brevity, we'll only show the code
    3415         for 'constants'.
     3616        for 'constants'::
    34163617
    34173618            sage: print rdf_wrapper
    34183619            # ...
    … …  
    34283629        double*.
    34293630
    34303631        The RRInterpreter version is more complicated, because it has to
    3431         call mpfr_init.
     3632        call mpfr_init::
     3633
    34323634            sage: print rr_wrapper
    34333635            # ...
    34343636                    cdef RealNumber rn
    … …  
    34463648
    34473649        And as described in the documentation for get_pxd, in
    34483650        Python-object based interpreters we actually allocate the
    3449         memory as a Python list.
     3651        memory as a Python list::
     3652
    34503653            sage: print el_wrapper
    34513654            # ...
    34523655                    val = args['constants']
    … …  
    34583661            ...
    34593662
    34603663        Of course, once we've allocated the memory, we eventually have
    3461         to free it.  (Again, we'll only look at 'constants'.)
     3664        to free it.  (Again, we'll only look at 'constants'.)::
     3665
    34623666            sage: print rdf_wrapper
    34633667            # ...
    34643668                def __dealloc__(self):
    … …  
    34683672            ...
    34693673
    34703674        The RRInterpreter code is more complicated again because it has
    3471         to call mpfr_clear.
     3675        to call mpfr_clear::
     3676
    34723677            sage: print rr_wrapper
    34733678            # ...
    34743679                def __dealloc__(self):
    … …  
    34923697        We optionally adjust the return value of the interpreter
    34933698        (currently only the RDF/float interpreter performs this step;
    34943699        this is the only place where domain=RDF differs than
    3495         domain=float):
     3700        domain=float)::
    34963701
    34973702            sage: print rdf_wrapper
    34983703            # ...
    … …  
    35183723        stack totally clear when the interpreter finishes.  However,
    35193724        this doesn't happen if the C interpreter raises an exception.
    35203725        In that case, we have to clear out any remnants from the stack
    3521         in the wrapper.
     3726        in the wrapper::
     3727
    35223728            sage: print el_wrapper
    35233729            # ...
    35243730                    try:
    … …  
    35363742
    35373743        Finally, we define a cdef call_c method, for quickly calling
    35383744        this object from Cython.  (The method is omitted from
    3539         Python-object based interpreters.)
     3745        Python-object based interpreters.)::
    35403746            sage: print rdf_wrapper
    35413747            # ...
    35423748                cdef bint call_c(self,
    … …  
    35533759
    35543760        The method for the RR interpreter is slightly different, because
    35553761        the interpreter takes a pointer to a result location instead of
    3556         returning the value.
     3762        returning the value::
     3763
    35573764            sage: print rr_wrapper
    35583765            # ...
    35593766                cdef bint call_c(self,
    … …  
    35863793        ipow instruction is defined over.
    35873794
    35883795        First the part that maps instruction names to
    3589         (CompilerInstrSpec, opcode) pairs.
     3796        (CompilerInstrSpec, opcode) pairs::
    35903797
    35913798            sage: print rdf_wrapper
    35923799            # ...
    … …  
    36053812             }, ...)
    36063813
    36073814        There's also a table that maps opcodes to (instruction name,
    3608         CompilerInstrSpec) pairs:
     3815        CompilerInstrSpec) pairs::
     3816
    36093817            sage: print rdf_wrapper
    36103818            # ...
    36113819            metadata = InterpreterMetadata(...,  by_opcode=[
    … …  
    36213829            ...
    36223830             ], ...)
    36233831
    3624         And then the ipow range:
     3832        And then the ipow range::
     3833
    36253834            sage: print rdf_wrapper
    36263835            # ...
    36273836            metadata = InterpreterMetadata(...,
    … …  
    36413850        EXAMPLES:
    36423851
    36433852        First we get the InterpreterSpec for several interpreters:
     3853
    36443854            sage: from sage.ext.gen_interpreters import *
    36453855            sage: rdf_spec = RDFInterpreter()
    36463856            sage: rr_spec = RRInterpreter()
    36473857            sage: el_spec = ElementInterpreter()
    36483858
    3649         Then we get the corresponding .pxd:
     3859        Then we get the corresponding .pxd::
     3860
    36503861            sage: rdf_pxd = InterpreterGenerator(rdf_spec).get_pxd()
    36513862            sage: rr_pxd = InterpreterGenerator(rr_spec).get_pxd()
    36523863            sage: el_pxd = InterpreterGenerator(el_spec).get_pxd()
    … …  
    36553866
    36563867        Each .pxd starts with a file header; this can be
    36573868        customized on a per-interpreter basis (some blank lines have been
    3658         elided below):
     3869        elided below)::
     3870
    36593871            sage: print rdf_pxd
    36603872            # Automatically generated by ext/gen_interpreters.py.  Do not edit!
    36613873            from cpython cimport PyObject
    … …  
    36683880            ...
    36693881
    36703882        Next and last is the declaration of the wrapper class, which
    3671         starts off with a list of member declarations.
     3883        starts off with a list of member declarations::
     3884
    36723885            sage: print rdf_pxd
    36733886            # ...
    36743887            cdef class Wrapper_rdf(Wrapper):
    … …  
    36893902        ElementInterpreter version.  To simplify our handling of
    36903903        reference counting and garbage collection, in a Python-object
    36913904        based interpreter, we allocate arrays as Python lists,
    3692         and then pull the array out of the innards of the list.
     3905        and then pull the array out of the innards of the list::
     3906
    36933907            sage: print el_pxd
    36943908            # ...
    36953909                cdef object _list_stack
    … …  
    36993913
    37003914        Then, at the end of the wrapper class, we declare a cdef method
    37013915        for quickly calling the wrapper object from Cython.  (This method
    3702         is omitted from Python-object based interpreters.)
     3916        is omitted from Python-object based interpreters.)::
     3917
    37033918            sage: print rdf_pxd
    37043919            # ...
    37053920                cdef bint call_c(self,
    … …  
    37223937    Writes value to the file named fn, if value is different than
    37233938    the current contents.
    37243939
    3725     EXAMPLES:
     3940    EXAMPLES::
     3941
    37263942        sage: from sage.ext.gen_interpreters import *
    37273943        sage: def last_modification(fn): return os.stat(fn).st_mtime
    37283944        sage: fn = tmp_filename('gen_interp')
    … …  
    37683984    Given an InterpreterSpec, writes the C interpreter and the Cython
    37693985    wrapper (generates a pyx and a pxd file).
    37703986
    3771     EXAMPLES:
     3987    EXAMPLES::
     3988
    37723989        sage: from sage.ext.gen_interpreters import *
    37733990        sage: testdir = tmp_filename()
    37743991        sage: os.mkdir(testdir)
    … …  
    37793996    """
    37803997    ig = InterpreterGenerator(interp_spec)
    37813998    interp_fn = '%s/interp_%s.c' % (dir, interp_spec.name)
     3999    header_fn = '%s/interp_%s.h' % (dir, interp_spec.name)
    37824000    wrapper_fn = '%s/wrapper_%s.pyx' % (dir, interp_spec.name)
    37834001    pxd_fn = '%s/wrapper_%s.pxd' % (dir, interp_spec.name)
    37844002    interp = ig.get_interpreter()
     4003    header = ig.get_interpreter_header()
    37854004    wrapper = ig.get_wrapper()
    37864005    pxd = ig.get_pxd()
    37874006    write_if_changed(interp_fn, interp)
     4007    write_if_changed(header_fn, header)
    37884008    write_if_changed(wrapper_fn, wrapper)
    37894009    write_if_changed(pxd_fn, pxd)
    37904010
    … …  
    37934013    Check whether the interpreter and wrapper sources have been written
    37944014    since the last time this module was changed.  If not, write them.
    37954015
    3796     EXAMPLES:
     4016    EXAMPLES::
     4017
    37974018        sage: from sage.ext.gen_interpreters import *
    37984019        sage: testdir = tmp_filename()
    37994020        sage: os.mkdir(testdir)