From bfd8290a716cb5a77d249003b3bcf16d24b3419d Mon Sep 17 00:00:00 2001 From: Dimitri Tcaciuc Date: Wed, 8 Aug 2012 20:31:54 -0700 Subject: [PATCH] Doc: fixing miscellaneous warnings and missing refs --- docs/conf.py | 5 ++++- docs/sphinxext/cython_highlighting.py | 3 ++- docs/sphinxext/ipython_console_highlighting.py | 4 +++- docs/src/reference/compilation.rst | 2 +- docs/src/reference/language_basics.rst | 5 +++++ docs/src/tutorial/numpy.rst | 2 +- docs/src/tutorial/pypy.rst | 2 +- docs/src/userguide/early_binding_for_speed.rst | 2 +- docs/src/userguide/extension_types.rst | 6 ++++-- docs/src/userguide/external_C_code.rst | 12 +++++++++--- docs/src/userguide/language_basics.rst | 7 +++++++ docs/src/userguide/numpy_tutorial.rst | 6 +++--- docs/src/userguide/parallelism.rst | 1 - docs/src/userguide/pyrex_differences.rst | 7 +++++-- docs/src/userguide/sharing_declarations.rst | 2 ++ docs/src/userguide/source_files_and_compilation.rst | 2 ++ 16 files changed, 50 insertions(+), 18 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 51d80a0..14dfa1e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ highlight_language = 'cython' # Add any Sphinx extension module names here, as strings. They can be extensions # 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. templates_path = ['_templates'] @@ -173,3 +173,6 @@ latex_documents = [ # todo todo_include_todos = True + +# intersphinx for standard :keyword:s (def, for, etc.) +intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)} diff --git a/docs/sphinxext/cython_highlighting.py b/docs/sphinxext/cython_highlighting.py index 3a2e5f9..06e11b8 100644 --- a/docs/sphinxext/cython_highlighting.py +++ b/docs/sphinxext/cython_highlighting.py @@ -179,4 +179,5 @@ class CythonLexer(RegexLexer): def analyse_text(text): return shebang_matches(text, r'pythonw?(2\.\d)?') -highlighting.lexers['cython'] = CythonLexer() +def setup(app): + app.add_lexer('cython', CythonLexer()) diff --git a/docs/sphinxext/ipython_console_highlighting.py b/docs/sphinxext/ipython_console_highlighting.py index 4f0104d..b9b4f5f 100644 --- a/docs/sphinxext/ipython_console_highlighting.py +++ b/docs/sphinxext/ipython_console_highlighting.py @@ -72,4 +72,6 @@ class IPythonConsoleLexer(Lexer): pylexer.get_tokens_unprocessed(curcode)): yield item -highlighting.lexers['ipython'] = IPythonConsoleLexer() + +def setup(app): + app.add_lexer('ipython', IPythonConsoleLexer()) diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst index 69c9cb9..be2a3c6 100644 --- a/docs/src/reference/compilation.rst +++ b/docs/src/reference/compilation.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _compilation: +.. _compilation-reference: ============= Compilation diff --git a/docs/src/reference/language_basics.rst b/docs/src/reference/language_basics.rst index c17a6f5..1192355 100644 --- a/docs/src/reference/language_basics.rst +++ b/docs/src/reference/language_basics.rst @@ -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. + The cdef Statement ================== @@ -531,6 +532,8 @@ Callable from Python * Return Python objects * See **Parameters** for special consideration +.. _cdef: + Callable from C ================ @@ -538,6 +541,8 @@ Callable from C * Are called with either Python objects or C values. * Can return either Python objects or C values. +.. _cpdef: + Callable from both Python and C ================================ diff --git a/docs/src/tutorial/numpy.rst b/docs/src/tutorial/numpy.rst index fec107f..34f5479 100644 --- a/docs/src/tutorial/numpy.rst +++ b/docs/src/tutorial/numpy.rst @@ -286,7 +286,7 @@ function call.) 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`. 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 other use (attribute lookup or indexing) can potentially segfault or corrupt data (rather than raising exceptions as they would in Python). diff --git a/docs/src/tutorial/pypy.rst b/docs/src/tutorial/pypy.rst index 9d938a3..6d1dd5b 100644 --- a/docs/src/tutorial/pypy.rst +++ b/docs/src/tutorial/pypy.rst @@ -119,7 +119,7 @@ may exhibit substantially different performance characteristics in cpyext. Functions returning borrowed references were already mentioned as requiring special care, but they also induce substantially more runtime overhead because 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 characteristics, e.g. :c:func:`PyDict_Next()` for dict iteration. While diff --git a/docs/src/userguide/early_binding_for_speed.rst b/docs/src/userguide/early_binding_for_speed.rst index d44498d..df3b013 100644 --- a/docs/src/userguide/early_binding_for_speed.rst +++ b/docs/src/userguide/early_binding_for_speed.rst @@ -102,7 +102,7 @@ overheads. Consider this code: .. note:: 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 efficiently callable as a C function, but still accessible from pure Python diff --git a/docs/src/userguide/extension_types.rst b/docs/src/userguide/extension_types.rst index 9d37c1d..47ee7e9 100644 --- a/docs/src/userguide/extension_types.rst +++ b/docs/src/userguide/extension_types.rst @@ -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 interface to them. +.. _readonly: + Attributes ============ @@ -464,7 +466,7 @@ built-in complex object.:: .. sourcecode:: c - ctypedef struct { + typedef struct { ... } PyComplexObject; @@ -475,7 +477,7 @@ built-in complex object.:: 3. When declaring an external extension type, you don't declare any methods. Declaration of methods is not required in order to call them, 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 declare those C members which you wish to access. diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst index a911def..bb35e4d 100644 --- a/docs/src/userguide/external_C_code.rst +++ b/docs/src/userguide/external_C_code.rst @@ -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. 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 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 as :meth:`foo()`. @@ -157,6 +157,8 @@ A few more tricks and tips: cdef extern from *: ... +.. _struct-union-enum-styles: + 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`` 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`. +.. _api: + C API Declarations ------------------- @@ -441,7 +445,7 @@ Releasing the GIL ^^^^^^^^^^^^^^^^^ You can release the GIL around a section of code using the -:keyword:`with nogil` statement:: +``with nogil`` statement:: with nogil: @@ -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 re-acquiring the GIL. Cython currently does not check this. +.. _gil: + Acquiring the GIL ^^^^^^^^^^^^^^^^^ diff --git a/docs/src/userguide/language_basics.rst b/docs/src/userguide/language_basics.rst index f81271a..49fd7a5 100644 --- a/docs/src/userguide/language_basics.rst +++ b/docs/src/userguide/language_basics.rst @@ -1,6 +1,11 @@ .. highlight:: cython .. _language-basics: +.. _struct: +.. _union: +.. _enum: +.. _ctypedef: + ***************** Language Basics @@ -34,6 +39,8 @@ and C :keyword:`struct`, :keyword:`union` or :keyword:`enum` types:: soft = 2 runny = 3 +See also :ref:`struct-union-enum-styles` + There is currently no special syntax for defining a constant, but you can use an anonymous :keyword:`enum` declaration for this purpose, for example,:: diff --git a/docs/src/userguide/numpy_tutorial.rst b/docs/src/userguide/numpy_tutorial.rst index aafeea7..8c86b0c 100644 --- a/docs/src/userguide/numpy_tutorial.rst +++ b/docs/src/userguide/numpy_tutorial.rst @@ -440,14 +440,14 @@ function call.) .. Warning:: 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`. - Setting such objects to :keyword:`None` is entirely legal, but all you can do with them + objects (like ``f``, ``g`` and ``h`` in our sample code) to ``None``. + 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) can potentially segfault or corrupt data (rather than raising exceptions as they would in Python). 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 ================== diff --git a/docs/src/userguide/parallelism.rst b/docs/src/userguide/parallelism.rst index d311440..1f240f8 100644 --- a/docs/src/userguide/parallelism.rst +++ b/docs/src/userguide/parallelism.rst @@ -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 or parallel regions due to OpenMP restrictions. -__ nogil_ .. function:: prange([start,] stop[, step][, nogil=False][, schedule=None[, chunksize=None]][, num_threads=None]) diff --git a/docs/src/userguide/pyrex_differences.rst b/docs/src/userguide/pyrex_differences.rst index 7c97948..4fc9aa4 100644 --- a/docs/src/userguide/pyrex_differences.rst +++ b/docs/src/userguide/pyrex_differences.rst @@ -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). + +.. _inline: + cdef inline ============= @@ -284,7 +287,7 @@ with corresponding ``.pyx`` file:: 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. C++ Exception handling @@ -317,7 +320,7 @@ literals like ``u'abcd'`` to unicode objects. 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 `_, Cython emits a (non-spoofable and faster) typecheck whenever diff --git a/docs/src/userguide/sharing_declarations.rst b/docs/src/userguide/sharing_declarations.rst index de3e726..18ca42b 100644 --- a/docs/src/userguide/sharing_declarations.rst +++ b/docs/src/userguide/sharing_declarations.rst @@ -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 is the only file one needs. +.. _cimport: + The cimport statement ======================= diff --git a/docs/src/userguide/source_files_and_compilation.rst b/docs/src/userguide/source_files_and_compilation.rst index 32b7df6..c2e833d 100644 --- a/docs/src/userguide/source_files_and_compilation.rst +++ b/docs/src/userguide/source_files_and_compilation.rst @@ -6,6 +6,8 @@ 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 ``.pyx`` extension, for example a module called primes would have a source file named :file:`primes.pyx`. -- 2.7.4