Commit bfd8290a authored by Dimitri Tcaciuc's avatar Dimitri Tcaciuc

Doc: fixing miscellaneous warnings and missing refs

parent cfdf7e3d
...@@ -31,7 +31,7 @@ highlight_language = 'cython' ...@@ -31,7 +31,7 @@ highlight_language = 'cython'
# Add any Sphinx extension module names here, as strings. They can be extensions # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo'] extensions = ['ipython_console_highlighting', 'cython_highlighting', 'sphinx.ext.pngmath', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -173,3 +173,6 @@ latex_documents = [ ...@@ -173,3 +173,6 @@ latex_documents = [
# todo # todo
todo_include_todos = True todo_include_todos = True
# intersphinx for standard :keyword:s (def, for, etc.)
intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}
...@@ -179,4 +179,5 @@ class CythonLexer(RegexLexer): ...@@ -179,4 +179,5 @@ class CythonLexer(RegexLexer):
def analyse_text(text): def analyse_text(text):
return shebang_matches(text, r'pythonw?(2\.\d)?') return shebang_matches(text, r'pythonw?(2\.\d)?')
highlighting.lexers['cython'] = CythonLexer() def setup(app):
app.add_lexer('cython', CythonLexer())
...@@ -72,4 +72,6 @@ class IPythonConsoleLexer(Lexer): ...@@ -72,4 +72,6 @@ class IPythonConsoleLexer(Lexer):
pylexer.get_tokens_unprocessed(curcode)): pylexer.get_tokens_unprocessed(curcode)):
yield item yield item
highlighting.lexers['ipython'] = IPythonConsoleLexer()
def setup(app):
app.add_lexer('ipython', IPythonConsoleLexer())
.. highlight:: cython .. highlight:: cython
.. _compilation: .. _compilation-reference:
============= =============
Compilation Compilation
......
...@@ -112,6 +112,7 @@ However with Cython it is possible to gain significant speed-ups through the use ...@@ -112,6 +112,7 @@ However with Cython it is possible to gain significant speed-ups through the use
Providing static typing to parameters and variables is convenience to speed up your code, but it is not a necessity. Optimize where and when needed. Providing static typing to parameters and variables is convenience to speed up your code, but it is not a necessity. Optimize where and when needed.
The cdef Statement The cdef Statement
================== ==================
...@@ -531,6 +532,8 @@ Callable from Python ...@@ -531,6 +532,8 @@ Callable from Python
* Return Python objects * Return Python objects
* See **Parameters** for special consideration * See **Parameters** for special consideration
.. _cdef:
Callable from C Callable from C
================ ================
...@@ -538,6 +541,8 @@ Callable from C ...@@ -538,6 +541,8 @@ Callable from C
* Are called with either Python objects or C values. * Are called with either Python objects or C values.
* Can return either Python objects or C values. * Can return either Python objects or C values.
.. _cpdef:
Callable from both Python and C Callable from both Python and C
================================ ================================
......
...@@ -286,7 +286,7 @@ function call.) ...@@ -286,7 +286,7 @@ function call.)
Speed comes with some cost. Especially it can be dangerous to set typed Speed comes with some cost. Especially it can be dangerous to set typed
objects (like ``f``, ``g`` and ``h`` in our sample code) to objects (like ``f``, ``g`` and ``h`` in our sample code) to
:keyword:`None`. Setting such objects to :keyword:`None` is entirely ``None``. Setting such objects to ``None`` is entirely
legal, but all you can do with them is check whether they are None. All legal, but all you can do with them is check whether they are None. All
other use (attribute lookup or indexing) can potentially segfault or other use (attribute lookup or indexing) can potentially segfault or
corrupt data (rather than raising exceptions as they would in Python). corrupt data (rather than raising exceptions as they would in Python).
......
...@@ -119,7 +119,7 @@ may exhibit substantially different performance characteristics in cpyext. ...@@ -119,7 +119,7 @@ may exhibit substantially different performance characteristics in cpyext.
Functions returning borrowed references were already mentioned as requiring Functions returning borrowed references were already mentioned as requiring
special care, but they also induce substantially more runtime overhead because special care, but they also induce substantially more runtime overhead because
they often create weak references in PyPy where they only return a plain they often create weak references in PyPy where they only return a plain
pointer in CPython. A visible example is :c:func:``PyTuple_GET_ITEM()`. pointer in CPython. A visible example is :c:func:`PyTuple_GET_ITEM()`.
Some more high-level functions may also show entirely different performance Some more high-level functions may also show entirely different performance
characteristics, e.g. :c:func:`PyDict_Next()` for dict iteration. While characteristics, e.g. :c:func:`PyDict_Next()` for dict iteration. While
......
...@@ -102,7 +102,7 @@ overheads. Consider this code: ...@@ -102,7 +102,7 @@ overheads. Consider this code:
.. note:: .. note::
in earlier versions of Cython, the :keyword:`cpdef` keyword is in earlier versions of Cython, the :keyword:`cpdef` keyword is
:keyword:`rdef` - but has the same effect). ``rdef`` - but has the same effect).
Here, we just have a single area method, declared as :keyword:`cpdef` to make it Here, we just have a single area method, declared as :keyword:`cpdef` to make it
efficiently callable as a C function, but still accessible from pure Python efficiently callable as a C function, but still accessible from pure Python
......
...@@ -37,6 +37,8 @@ particular extension type), or they may be of any C data type. So you can use ...@@ -37,6 +37,8 @@ particular extension type), or they may be of any C data type. So you can use
extension types to wrap arbitrary C data structures and provide a Python-like extension types to wrap arbitrary C data structures and provide a Python-like
interface to them. interface to them.
.. _readonly:
Attributes Attributes
============ ============
...@@ -464,7 +466,7 @@ built-in complex object.:: ...@@ -464,7 +466,7 @@ built-in complex object.::
.. sourcecode:: c .. sourcecode:: c
ctypedef struct { typedef struct {
... ...
} PyComplexObject; } PyComplexObject;
...@@ -475,7 +477,7 @@ built-in complex object.:: ...@@ -475,7 +477,7 @@ built-in complex object.::
3. When declaring an external extension type, you don't declare any 3. When declaring an external extension type, you don't declare any
methods. Declaration of methods is not required in order to call them, methods. Declaration of methods is not required in order to call them,
because the calls are Python method calls. Also, as with because the calls are Python method calls. Also, as with
:keyword:`structs` and :keyword:`unions`, if your extension class :keyword:`struct` and :keyword:`union`, if your extension class
declaration is inside a :keyword:`cdef` extern from block, you only need to declaration is inside a :keyword:`cdef` extern from block, you only need to
declare those C members which you wish to access. declare those C members which you wish to access.
......
...@@ -132,12 +132,12 @@ match the C ones, and in some cases they shouldn't or can't. In particular: ...@@ -132,12 +132,12 @@ match the C ones, and in some cases they shouldn't or can't. In particular:
be used for this new type. be used for this new type.
5. If the header file uses macros to define constants, translate them into a 5. If the header file uses macros to define constants, translate them into a
dummy ``enum`` declaration. dummy :keyword:`enum` declaration.
6. If the header file defines a function using a macro, declare it as though 6. If the header file defines a function using a macro, declare it as though
it were an ordinary function, with appropriate argument and result types. it were an ordinary function, with appropriate argument and result types.
7. For archaic reasons C uses the keyword :keyword:`void` to declare a function 7. For archaic reasons C uses the keyword ``void`` to declare a function
taking no parameters. In Cython as in Python, simply declare such functions taking no parameters. In Cython as in Python, simply declare such functions
as :meth:`foo()`. as :meth:`foo()`.
...@@ -157,6 +157,8 @@ A few more tricks and tips: ...@@ -157,6 +157,8 @@ A few more tricks and tips:
cdef extern from *: cdef extern from *:
... ...
.. _struct-union-enum-styles:
Styles of struct, union and enum declaration Styles of struct, union and enum declaration
---------------------------------------------- ----------------------------------------------
...@@ -341,6 +343,8 @@ If the Cython module resides within a package, then the name of the ``.h`` ...@@ -341,6 +343,8 @@ If the Cython module resides within a package, then the name of the ``.h``
file consists of the full dotted name of the module, e.g. a module called file consists of the full dotted name of the module, e.g. a module called
:mod:`foo.spam` would have a header file called :file:`foo.spam.h`. :mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
.. _api:
C API Declarations C API Declarations
------------------- -------------------
...@@ -441,7 +445,7 @@ Releasing the GIL ...@@ -441,7 +445,7 @@ Releasing the GIL
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
You can release the GIL around a section of code using the You can release the GIL around a section of code using the
:keyword:`with nogil` statement:: ``with nogil`` statement::
with nogil: with nogil:
<code to be executed with the GIL released> <code to be executed with the GIL released>
...@@ -450,6 +454,8 @@ Code in the body of the statement must not manipulate Python objects in any ...@@ -450,6 +454,8 @@ Code in the body of the statement must not manipulate Python objects in any
way, and must not call anything that manipulates Python objects without first way, and must not call anything that manipulates Python objects without first
re-acquiring the GIL. Cython currently does not check this. re-acquiring the GIL. Cython currently does not check this.
.. _gil:
Acquiring the GIL Acquiring the GIL
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
......
.. highlight:: cython .. highlight:: cython
.. _language-basics: .. _language-basics:
.. _struct:
.. _union:
.. _enum:
.. _ctypedef:
***************** *****************
Language Basics Language Basics
...@@ -34,6 +39,8 @@ and C :keyword:`struct`, :keyword:`union` or :keyword:`enum` types:: ...@@ -34,6 +39,8 @@ and C :keyword:`struct`, :keyword:`union` or :keyword:`enum` types::
soft = 2 soft = 2
runny = 3 runny = 3
See also :ref:`struct-union-enum-styles`
There is currently no special syntax for defining a constant, but you can use There is currently no special syntax for defining a constant, but you can use
an anonymous :keyword:`enum` declaration for this purpose, for example,:: an anonymous :keyword:`enum` declaration for this purpose, for example,::
......
...@@ -440,14 +440,14 @@ function call.) ...@@ -440,14 +440,14 @@ function call.)
.. Warning:: .. Warning::
Speed comes with some cost. Especially it can be dangerous to set typed Speed comes with some cost. Especially it can be dangerous to set typed
objects (like ``f``, ``g`` and ``h`` in our sample code) to :keyword:`None`. objects (like ``f``, ``g`` and ``h`` in our sample code) to ``None``.
Setting such objects to :keyword:`None` is entirely legal, but all you can do with them Setting such objects to ``None`` is entirely legal, but all you can do with them
is check whether they are None. All other use (attribute lookup or indexing) is check whether they are None. All other use (attribute lookup or indexing)
can potentially segfault or corrupt data (rather than raising exceptions as can potentially segfault or corrupt data (rather than raising exceptions as
they would in Python). they would in Python).
The actual rules are a bit more complicated but the main message is clear: Do The actual rules are a bit more complicated but the main message is clear: Do
not use typed objects without knowing that they are not set to None. not use typed objects without knowing that they are not set to ``None``.
More generic code More generic code
================== ==================
......
...@@ -16,7 +16,6 @@ It currently supports OpenMP, but later on more backends might be supported. ...@@ -16,7 +16,6 @@ It currently supports OpenMP, but later on more backends might be supported.
.. NOTE:: Functionality in this module may only be used from the main thread .. NOTE:: Functionality in this module may only be used from the main thread
or parallel regions due to OpenMP restrictions. or parallel regions due to OpenMP restrictions.
__ nogil_
.. function:: prange([start,] stop[, step][, nogil=False][, schedule=None[, chunksize=None]][, num_threads=None]) .. function:: prange([start,] stop[, step][, nogil=False][, schedule=None[, chunksize=None]][, num_threads=None])
......
...@@ -78,6 +78,9 @@ http://www.python.org/dev/peps/pep-0308/:: ...@@ -78,6 +78,9 @@ http://www.python.org/dev/peps/pep-0308/::
Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C).
.. _inline:
cdef inline cdef inline
============= =============
...@@ -284,7 +287,7 @@ with corresponding ``.pyx`` file:: ...@@ -284,7 +287,7 @@ with corresponding ``.pyx`` file::
Function pointers in structs Function pointers in structs
============================= =============================
Functions declared in :keyword:`structs` are automatically converted to Functions declared in :keyword:`struct` are automatically converted to
function pointers for convenience. function pointers for convenience.
C++ Exception handling C++ Exception handling
...@@ -317,7 +320,7 @@ literals like ``u'abcd'`` to unicode objects. ...@@ -317,7 +320,7 @@ literals like ``u'abcd'`` to unicode objects.
Automatic ``typecheck`` Automatic ``typecheck``
======================== ========================
Rather than introducing a new keyword :keyword:`typecheck` as explained in the Rather than introducing a new keyword ``typecheck`` as explained in the
`Pyrex docs `Pyrex docs
<http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/special_methods.html>`_, <http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/special_methods.html>`_,
Cython emits a (non-spoofable and faster) typecheck whenever Cython emits a (non-spoofable and faster) typecheck whenever
......
...@@ -59,6 +59,8 @@ corresponding definition file also defines that type (see below). ...@@ -59,6 +59,8 @@ corresponding definition file also defines that type (see below).
If one doesn't need to :keyword:`cimport` anything from this module, then this If one doesn't need to :keyword:`cimport` anything from this module, then this
is the only file one needs. is the only file one needs.
.. _cimport:
The cimport statement The cimport statement
======================= =======================
......
...@@ -6,6 +6,8 @@ ...@@ -6,6 +6,8 @@
Source Files and Compilation Source Files and Compilation
**************************** ****************************
.. note:: See :ref:`compilation-reference` reference section for more details
Cython source file names consist of the name of the module followed by a Cython source file names consist of the name of the module followed by a
``.pyx`` extension, for example a module called primes would have a source ``.pyx`` extension, for example a module called primes would have a source
file named :file:`primes.pyx`. file named :file:`primes.pyx`.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment