From 6f7b816ab8ac2663039614da81105f888d81606a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 3 Aug 2007 07:32:31 +0000 Subject: [PATCH] Replace .. include by a new .. literalinclude which doesn't raise if the file isn't found. --- Doc-26/c-api/newtypes.rst | 3 +- Doc-26/documenting/markup.rst | 18 +++++--- Doc-26/extending/embedding.rst | 3 +- Doc-26/extending/newtypes.rst | 18 +++----- Doc-26/library/ast.rst | 8 ++-- Doc-26/library/datetime.rst | 3 +- Doc-26/library/email-examples.rst | 17 +++---- Doc-26/library/exceptions.rst | 2 +- Doc-26/library/sqlite3.rst | 71 ++++++++---------------------- Doc-26/library/xml.dom.minidom.rst | 4 +- Doc-3k/c-api/newtypes.rst | 3 +- Doc-3k/documenting/markup.rst | 18 +++++--- Doc-3k/extending/embedding.rst | 3 +- Doc-3k/extending/newtypes.rst | 18 +++----- Doc-3k/library/datetime.rst | 3 +- Doc-3k/library/email-examples.rst | 17 +++---- Doc-3k/library/exceptions.rst | 2 +- Doc-3k/library/sqlite3.rst | 71 ++++++++---------------------- Doc-3k/library/xml.dom.minidom.rst | 4 +- sphinx/directives.py | 33 +++++++++++++- 20 files changed, 130 insertions(+), 189 deletions(-) diff --git a/Doc-26/c-api/newtypes.rst b/Doc-26/c-api/newtypes.rst index e41220237..96c04d722 100644 --- a/Doc-26/c-api/newtypes.rst +++ b/Doc-26/c-api/newtypes.rst @@ -356,9 +356,8 @@ The structure definition for :ctype:`PyTypeObject` can be found in :file:`Include/object.h`. For convenience of reference, this repeats the definition found there: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: The type object structure extends the :ctype:`PyVarObject` structure. The :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, diff --git a/Doc-26/documenting/markup.rst b/Doc-26/documenting/markup.rst index eea21e461..1470d2b76 100644 --- a/Doc-26/documenting/markup.rst +++ b/Doc-26/documenting/markup.rst @@ -8,7 +8,7 @@ markup. This section contains the reference material for these facilities. Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -XXX: file-wide metadata +.. XXX: file-wide metadata Meta-information markup ----------------------- @@ -250,11 +250,13 @@ Syntax highlighting is handled in a smart way: Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the -standard ``include`` directive with the ``literal`` option flag. For example, -to include the Python source file :file:`example.py`, use:: +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: - .. include:: example.py - :literal: + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. Inline markup @@ -741,3 +743,9 @@ They are set in the build configuration file, see :ref:`doc-build-config`. Replaced by either today's date, or the date set in the build configuration file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. diff --git a/Doc-26/extending/embedding.rst b/Doc-26/extending/embedding.rst index ab6c9dcff..1dfec815a 100644 --- a/Doc-26/extending/embedding.rst +++ b/Doc-26/extending/embedding.rst @@ -132,9 +132,8 @@ section). The code to run a function defined in a Python script is: +.. literalinclude:: ../includes/run-func.c -.. include:: ../includes/run-func.c - :literal: This code loads a Python script using ``argv[1]``, and calls the function named in ``argv[2]``. Its integer arguments are the other values of the ``argv`` diff --git a/Doc-26/extending/newtypes.rst b/Doc-26/extending/newtypes.rst index c837ff5a0..8a38e34d1 100644 --- a/Doc-26/extending/newtypes.rst +++ b/Doc-26/extending/newtypes.rst @@ -47,9 +47,8 @@ object. This sort of thing can only be explained by example, so here's a minimal, but complete, module that defines a new type: +.. literalinclude:: ../includes/noddy.c -.. include:: ../includes/noddy.c - :literal: Now that's quite a bit to take in at once, but hopefully bits will seem familiar from the last chapter. @@ -248,9 +247,8 @@ Let's expend the basic example to add some data and methods. Let's also make the type usable as a base class. We'll create a new module, :mod:`noddy2` that adds these capabilities: +.. literalinclude:: ../includes/noddy2.c -.. include:: ../includes/noddy2.c - :literal: This version of the module has a number of changes. @@ -557,9 +555,8 @@ version of our module, the instance variables :attr:`first` and :attr:`last` could be set to non-string values or even deleted. We want to make sure that these attributes always contain strings. +.. literalinclude:: ../includes/noddy3.c -.. include:: ../includes/noddy3.c - :literal: To provide greater control, over the :attr:`first` and :attr:`last` attributes, we'll use custom getter and setter functions. Here are the functions for @@ -708,9 +705,8 @@ garbage collector to the :class:`Noddy` example. To support cyclic garbage collection, types need to fill two slots and set a class flag that enables these slots: +.. literalinclude:: ../includes/noddy4.c -.. include:: ../includes/noddy4.c - :literal: The traversal method provides access to subobjects that could participate in cycles:: @@ -839,9 +835,8 @@ increases an internal counter. :: >>> print s.increment() 2 +.. literalinclude:: ../includes/shoddy.c -.. include:: ../includes/shoddy.c - :literal: As you can see, the source code closely resembles the :class:`Noddy` examples in previous sections. We will break down the main differences between them. :: @@ -917,9 +912,8 @@ implement and what they do. Here is the definition of :ctype:`PyTypeObject`, with some fields only used in debug builds omitted: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: Now that's a *lot* of methods. Don't worry too much though - if you have a type you want to define, the chances are very good that you will only implement a diff --git a/Doc-26/library/ast.rst b/Doc-26/library/ast.rst index 4d3acef54..15a73cf8c 100644 --- a/Doc-26/library/ast.rst +++ b/Doc-26/library/ast.rst @@ -1,8 +1,7 @@ .. _ast: -********************* Abstract Syntax Trees -********************* +===================== .. module:: _ast @@ -49,12 +48,11 @@ values (marked with an asterisk), the values are represented as Python lists. Abstract Grammar -================ +---------------- The module defines a string constant ``__version__`` which is the decimal subversion revision number of the file shown below. The abstract grammar is currently defined as follows: - -.. XXX includefile ../../Parser/Python.asdl +.. literalinclude:: ../../Parser/Python.asdl diff --git a/Doc-26/library/datetime.rst b/Doc-26/library/datetime.rst index 917808d9e..55c1606c3 100644 --- a/Doc-26/library/datetime.rst +++ b/Doc-26/library/datetime.rst @@ -1253,9 +1253,8 @@ There is one more :class:`tzinfo` method that a subclass may wish to override: Example :class:`tzinfo` classes: +.. literalinclude:: ../includes/tzinfo-examples.py -.. include:: ../includes/tzinfo-examples.py - :literal: Note that there are unavoidable subtleties twice per year in a :class:`tzinfo` subclass accounting for both standard and daylight time, at the DST transition diff --git a/Doc-26/library/email-examples.rst b/Doc-26/library/email-examples.rst index 482897071..64a994433 100644 --- a/Doc-26/library/email-examples.rst +++ b/Doc-26/library/email-examples.rst @@ -6,33 +6,28 @@ and send simple email messages, as well as more complex MIME messages. First, let's see how to create and send a simple text message: +.. literalinclude:: ../includes/email-simple.py -.. include:: ../includes/email-simple.py - :literal: Here's an example of how to send a MIME message containing a bunch of family pictures that may be residing in a directory: +.. literalinclude:: ../includes/email-mime.py -.. include:: ../includes/email-mime.py - :literal: Here's an example of how to send the entire contents of a directory as an email -message: [#]_ +message: [1]_ +.. literalinclude:: ../includes/email-dir.py -.. include:: ../includes/email-dir.py - :literal: And finally, here's an example of how to unpack a MIME message like the one above, into a directory of files: - -.. include:: ../includes/email-unpack.py - :literal: +.. literalinclude:: ../includes/email-unpack.py .. rubric:: Footnotes -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. +.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples. diff --git a/Doc-26/library/exceptions.rst b/Doc-26/library/exceptions.rst index c345fa99c..9081cf797 100644 --- a/Doc-26/library/exceptions.rst +++ b/Doc-26/library/exceptions.rst @@ -479,4 +479,4 @@ module for more information. The class hierarchy for built-in exceptions is: -.. XXX includefile ../../Lib/test/exception_hierarchy.txt +.. literalinclude:: ../../Lib/test/exception_hierarchy.txt diff --git a/Doc-26/library/sqlite3.rst b/Doc-26/library/sqlite3.rst index 4fdaee07d..71c5a05fd 100644 --- a/Doc-26/library/sqlite3.rst +++ b/Doc-26/library/sqlite3.rst @@ -200,8 +200,7 @@ Module functions and constants This can be used to build a shell for SQLite, as in the following example: - .. include:: ../includes/sqlite3/complete_statement.py - :literal: + .. literalinclude:: ../includes/sqlite3/complete_statement.py .. function:: enable_callback_tracebacks(flag) @@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/md5func.py - :literal: + .. literalinclude:: ../includes/sqlite3/md5func.py .. method:: Connection.create_aggregate(name, num_params, aggregate_class) @@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/mysumaggr.py - :literal: + .. literalinclude:: ../includes/sqlite3/mysumaggr.py .. method:: Connection.create_collation(name, callable) @@ -303,9 +298,7 @@ A :class:`Connection` instance has the following attributes and methods: The following example shows a custom collation that sorts "the wrong way": - - .. include:: ../includes/sqlite3/collation_reverse.py - :literal: + .. literalinclude:: ../includes/sqlite3/collation_reverse.py To remove a collation, call ``create_collation`` with None as callable:: @@ -349,9 +342,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/row_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/row_factory.py If returning a tuple doesn't suffice and you want name-based access to columns, you should consider setting :attr:`row_factory` to the highly-optimized @@ -379,9 +370,7 @@ A :class:`Connection` instance has the following attributes and methods: See the following example code for illustration: - - .. include:: ../includes/sqlite3/text_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/text_factory.py .. attribute:: Connection.total_changes @@ -407,15 +396,11 @@ A :class:`Cursor` instance has the following attributes and methods: This example shows how to use parameters with qmark style: - - .. include:: ../includes/sqlite3/execute_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_1.py This example shows how to use the named style: - - .. include:: ../includes/sqlite3/execute_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_2.py :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a Warning. Use @@ -429,15 +414,11 @@ A :class:`Cursor` instance has the following attributes and methods: sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding parameters instead of a sequence. - - .. include:: ../includes/sqlite3/executemany_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_1.py Here's a shorter example using a generator: - - .. include:: ../includes/sqlite3/executemany_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_2.py .. method:: Cursor.executescript(sql_script) @@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/executescript.py - :literal: + .. literalinclude:: ../includes/sqlite3/executescript.py .. attribute:: Cursor.rowcount @@ -559,9 +538,7 @@ Let's just use str and separate the coordinates using a semicolon. Then you need to give your class a method ``__conform__(self, protocol)`` which must return the converted value. The parameter *protocol* will be :class:`PrepareProtocol`. - -.. include:: ../includes/sqlite3/adapter_point_1.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_1.py Registering an adapter callable @@ -575,18 +552,14 @@ string representation and register the function with :meth:`register_adapter`. The type/class to adapt must be a new-style class, i. e. it must have :class:`object` as one of its bases. - -.. include:: ../includes/sqlite3/adapter_point_2.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_2.py The :mod:`sqlite3` module has two default adapters for Python's built-in :class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose we want to store :class:`datetime.datetime` objects not in ISO representation, but as a Unix timestamp. - -.. include:: ../includes/sqlite3/adapter_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_datetime.py Converting SQLite values to custom Python types @@ -630,9 +603,7 @@ for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. - -.. include:: ../includes/sqlite3/converter_point.py - :literal: +.. literalinclude:: ../includes/sqlite3/converter_point.py Default adapters and converters @@ -651,9 +622,7 @@ experimental SQLite date/time functions. The following example demonstrates this. - -.. include:: ../includes/sqlite3/pysqlite_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py .. _sqlite3-controlling-transactions: @@ -704,9 +673,7 @@ objects are created implicitly and these shortcut methods return the cursor objects. This way, you can execute a SELECT statement and iterate over it directly using only a single call on the :class:`Connection` object. - -.. include:: ../includes/sqlite3/shortcut_methods.py - :literal: +.. literalinclude:: ../includes/sqlite3/shortcut_methods.py Accessing columns by name instead of by index @@ -718,7 +685,5 @@ One useful feature of the :mod:`sqlite3` module is the builtin Rows wrapped with this class can be accessed both by index (like tuples) and case-insensitively by name: - -.. include:: ../includes/sqlite3/rowclass.py - :literal: +.. literalinclude:: ../includes/sqlite3/rowclass.py diff --git a/Doc-26/library/xml.dom.minidom.rst b/Doc-26/library/xml.dom.minidom.rst index d7a5e61c1..54c5f3d82 100644 --- a/Doc-26/library/xml.dom.minidom.rst +++ b/Doc-26/library/xml.dom.minidom.rst @@ -193,9 +193,7 @@ DOM Example This example program is a fairly realistic example of a simple program. In this particular case, we do not take much advantage of the flexibility of the DOM. - -.. include:: ../includes/minidom-example.py - :literal: +.. literalinclude:: ../includes/minidom-example.py .. _minidom-and-dom: diff --git a/Doc-3k/c-api/newtypes.rst b/Doc-3k/c-api/newtypes.rst index 5120c2cde..2d2fa4bb5 100644 --- a/Doc-3k/c-api/newtypes.rst +++ b/Doc-3k/c-api/newtypes.rst @@ -356,9 +356,8 @@ The structure definition for :ctype:`PyTypeObject` can be found in :file:`Include/object.h`. For convenience of reference, this repeats the definition found there: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: The type object structure extends the :ctype:`PyVarObject` structure. The :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, diff --git a/Doc-3k/documenting/markup.rst b/Doc-3k/documenting/markup.rst index eea21e461..1470d2b76 100644 --- a/Doc-3k/documenting/markup.rst +++ b/Doc-3k/documenting/markup.rst @@ -8,7 +8,7 @@ markup. This section contains the reference material for these facilities. Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation. -XXX: file-wide metadata +.. XXX: file-wide metadata Meta-information markup ----------------------- @@ -250,11 +250,13 @@ Syntax highlighting is handled in a smart way: Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the -standard ``include`` directive with the ``literal`` option flag. For example, -to include the Python source file :file:`example.py`, use:: +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: - .. include:: example.py - :literal: + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. Inline markup @@ -741,3 +743,9 @@ They are set in the build configuration file, see :ref:`doc-build-config`. Replaced by either today's date, or the date set in the build configuration file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. diff --git a/Doc-3k/extending/embedding.rst b/Doc-3k/extending/embedding.rst index ab6c9dcff..1dfec815a 100644 --- a/Doc-3k/extending/embedding.rst +++ b/Doc-3k/extending/embedding.rst @@ -132,9 +132,8 @@ section). The code to run a function defined in a Python script is: +.. literalinclude:: ../includes/run-func.c -.. include:: ../includes/run-func.c - :literal: This code loads a Python script using ``argv[1]``, and calls the function named in ``argv[2]``. Its integer arguments are the other values of the ``argv`` diff --git a/Doc-3k/extending/newtypes.rst b/Doc-3k/extending/newtypes.rst index c837ff5a0..8a38e34d1 100644 --- a/Doc-3k/extending/newtypes.rst +++ b/Doc-3k/extending/newtypes.rst @@ -47,9 +47,8 @@ object. This sort of thing can only be explained by example, so here's a minimal, but complete, module that defines a new type: +.. literalinclude:: ../includes/noddy.c -.. include:: ../includes/noddy.c - :literal: Now that's quite a bit to take in at once, but hopefully bits will seem familiar from the last chapter. @@ -248,9 +247,8 @@ Let's expend the basic example to add some data and methods. Let's also make the type usable as a base class. We'll create a new module, :mod:`noddy2` that adds these capabilities: +.. literalinclude:: ../includes/noddy2.c -.. include:: ../includes/noddy2.c - :literal: This version of the module has a number of changes. @@ -557,9 +555,8 @@ version of our module, the instance variables :attr:`first` and :attr:`last` could be set to non-string values or even deleted. We want to make sure that these attributes always contain strings. +.. literalinclude:: ../includes/noddy3.c -.. include:: ../includes/noddy3.c - :literal: To provide greater control, over the :attr:`first` and :attr:`last` attributes, we'll use custom getter and setter functions. Here are the functions for @@ -708,9 +705,8 @@ garbage collector to the :class:`Noddy` example. To support cyclic garbage collection, types need to fill two slots and set a class flag that enables these slots: +.. literalinclude:: ../includes/noddy4.c -.. include:: ../includes/noddy4.c - :literal: The traversal method provides access to subobjects that could participate in cycles:: @@ -839,9 +835,8 @@ increases an internal counter. :: >>> print s.increment() 2 +.. literalinclude:: ../includes/shoddy.c -.. include:: ../includes/shoddy.c - :literal: As you can see, the source code closely resembles the :class:`Noddy` examples in previous sections. We will break down the main differences between them. :: @@ -917,9 +912,8 @@ implement and what they do. Here is the definition of :ctype:`PyTypeObject`, with some fields only used in debug builds omitted: +.. literalinclude:: ../includes/typestruct.h -.. include:: ../includes/typestruct.h - :literal: Now that's a *lot* of methods. Don't worry too much though - if you have a type you want to define, the chances are very good that you will only implement a diff --git a/Doc-3k/library/datetime.rst b/Doc-3k/library/datetime.rst index 917808d9e..55c1606c3 100644 --- a/Doc-3k/library/datetime.rst +++ b/Doc-3k/library/datetime.rst @@ -1253,9 +1253,8 @@ There is one more :class:`tzinfo` method that a subclass may wish to override: Example :class:`tzinfo` classes: +.. literalinclude:: ../includes/tzinfo-examples.py -.. include:: ../includes/tzinfo-examples.py - :literal: Note that there are unavoidable subtleties twice per year in a :class:`tzinfo` subclass accounting for both standard and daylight time, at the DST transition diff --git a/Doc-3k/library/email-examples.rst b/Doc-3k/library/email-examples.rst index 482897071..64a994433 100644 --- a/Doc-3k/library/email-examples.rst +++ b/Doc-3k/library/email-examples.rst @@ -6,33 +6,28 @@ and send simple email messages, as well as more complex MIME messages. First, let's see how to create and send a simple text message: +.. literalinclude:: ../includes/email-simple.py -.. include:: ../includes/email-simple.py - :literal: Here's an example of how to send a MIME message containing a bunch of family pictures that may be residing in a directory: +.. literalinclude:: ../includes/email-mime.py -.. include:: ../includes/email-mime.py - :literal: Here's an example of how to send the entire contents of a directory as an email -message: [#]_ +message: [1]_ +.. literalinclude:: ../includes/email-dir.py -.. include:: ../includes/email-dir.py - :literal: And finally, here's an example of how to unpack a MIME message like the one above, into a directory of files: - -.. include:: ../includes/email-unpack.py - :literal: +.. literalinclude:: ../includes/email-unpack.py .. rubric:: Footnotes -.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. +.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples. diff --git a/Doc-3k/library/exceptions.rst b/Doc-3k/library/exceptions.rst index 68ca685cd..4dcaed881 100644 --- a/Doc-3k/library/exceptions.rst +++ b/Doc-3k/library/exceptions.rst @@ -472,4 +472,4 @@ module for more information. The class hierarchy for built-in exceptions is: -.. XXX includefile ../../Lib/test/exception_hierarchy.txt +.. literalinclude:: ../../Lib/test/exception_hierarchy.txt diff --git a/Doc-3k/library/sqlite3.rst b/Doc-3k/library/sqlite3.rst index 4fdaee07d..71c5a05fd 100644 --- a/Doc-3k/library/sqlite3.rst +++ b/Doc-3k/library/sqlite3.rst @@ -200,8 +200,7 @@ Module functions and constants This can be used to build a shell for SQLite, as in the following example: - .. include:: ../includes/sqlite3/complete_statement.py - :literal: + .. literalinclude:: ../includes/sqlite3/complete_statement.py .. function:: enable_callback_tracebacks(flag) @@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/md5func.py - :literal: + .. literalinclude:: ../includes/sqlite3/md5func.py .. method:: Connection.create_aggregate(name, num_params, aggregate_class) @@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/mysumaggr.py - :literal: + .. literalinclude:: ../includes/sqlite3/mysumaggr.py .. method:: Connection.create_collation(name, callable) @@ -303,9 +298,7 @@ A :class:`Connection` instance has the following attributes and methods: The following example shows a custom collation that sorts "the wrong way": - - .. include:: ../includes/sqlite3/collation_reverse.py - :literal: + .. literalinclude:: ../includes/sqlite3/collation_reverse.py To remove a collation, call ``create_collation`` with None as callable:: @@ -349,9 +342,7 @@ A :class:`Connection` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/row_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/row_factory.py If returning a tuple doesn't suffice and you want name-based access to columns, you should consider setting :attr:`row_factory` to the highly-optimized @@ -379,9 +370,7 @@ A :class:`Connection` instance has the following attributes and methods: See the following example code for illustration: - - .. include:: ../includes/sqlite3/text_factory.py - :literal: + .. literalinclude:: ../includes/sqlite3/text_factory.py .. attribute:: Connection.total_changes @@ -407,15 +396,11 @@ A :class:`Cursor` instance has the following attributes and methods: This example shows how to use parameters with qmark style: - - .. include:: ../includes/sqlite3/execute_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_1.py This example shows how to use the named style: - - .. include:: ../includes/sqlite3/execute_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/execute_2.py :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a Warning. Use @@ -429,15 +414,11 @@ A :class:`Cursor` instance has the following attributes and methods: sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding parameters instead of a sequence. - - .. include:: ../includes/sqlite3/executemany_1.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_1.py Here's a shorter example using a generator: - - .. include:: ../includes/sqlite3/executemany_2.py - :literal: + .. literalinclude:: ../includes/sqlite3/executemany_2.py .. method:: Cursor.executescript(sql_script) @@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods: Example: - - .. include:: ../includes/sqlite3/executescript.py - :literal: + .. literalinclude:: ../includes/sqlite3/executescript.py .. attribute:: Cursor.rowcount @@ -559,9 +538,7 @@ Let's just use str and separate the coordinates using a semicolon. Then you need to give your class a method ``__conform__(self, protocol)`` which must return the converted value. The parameter *protocol* will be :class:`PrepareProtocol`. - -.. include:: ../includes/sqlite3/adapter_point_1.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_1.py Registering an adapter callable @@ -575,18 +552,14 @@ string representation and register the function with :meth:`register_adapter`. The type/class to adapt must be a new-style class, i. e. it must have :class:`object` as one of its bases. - -.. include:: ../includes/sqlite3/adapter_point_2.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_point_2.py The :mod:`sqlite3` module has two default adapters for Python's built-in :class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose we want to store :class:`datetime.datetime` objects not in ISO representation, but as a Unix timestamp. - -.. include:: ../includes/sqlite3/adapter_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/adapter_datetime.py Converting SQLite values to custom Python types @@ -630,9 +603,7 @@ for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. - -.. include:: ../includes/sqlite3/converter_point.py - :literal: +.. literalinclude:: ../includes/sqlite3/converter_point.py Default adapters and converters @@ -651,9 +622,7 @@ experimental SQLite date/time functions. The following example demonstrates this. - -.. include:: ../includes/sqlite3/pysqlite_datetime.py - :literal: +.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py .. _sqlite3-controlling-transactions: @@ -704,9 +673,7 @@ objects are created implicitly and these shortcut methods return the cursor objects. This way, you can execute a SELECT statement and iterate over it directly using only a single call on the :class:`Connection` object. - -.. include:: ../includes/sqlite3/shortcut_methods.py - :literal: +.. literalinclude:: ../includes/sqlite3/shortcut_methods.py Accessing columns by name instead of by index @@ -718,7 +685,5 @@ One useful feature of the :mod:`sqlite3` module is the builtin Rows wrapped with this class can be accessed both by index (like tuples) and case-insensitively by name: - -.. include:: ../includes/sqlite3/rowclass.py - :literal: +.. literalinclude:: ../includes/sqlite3/rowclass.py diff --git a/Doc-3k/library/xml.dom.minidom.rst b/Doc-3k/library/xml.dom.minidom.rst index d7a5e61c1..54c5f3d82 100644 --- a/Doc-3k/library/xml.dom.minidom.rst +++ b/Doc-3k/library/xml.dom.minidom.rst @@ -193,9 +193,7 @@ DOM Example This example program is a fairly realistic example of a simple program. In this particular case, we do not take much advantage of the flexibility of the DOM. - -.. include:: ../includes/minidom-example.py - :literal: +.. literalinclude:: ../includes/minidom-example.py .. _minidom-and-dom: diff --git a/sphinx/directives.py b/sphinx/directives.py index 3cc2273e0..3da16c072 100644 --- a/sphinx/directives.py +++ b/sphinx/directives.py @@ -8,6 +8,7 @@ :copyright: 2007 by Georg Brandl. :license: Python license. """ +from __future__ import with_statement import re import string @@ -531,5 +532,33 @@ def highlightlang_directive(name, arguments, options, content, lineno, highlightlang_directive.content = 0 highlightlang_directive.arguments = (1, 0, 0) -directives.register_directive('highlightlang', - highlightlang_directive) +directives.register_directive('highlightlang', highlightlang_directive) + + +# ------ literalinclude directive --------------------------------------------------- + +def literalinclude_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + """Like .. include:: :literal:, but only warns if the include file is not found.""" + if not state.document.settings.file_insertion_enabled: + return [state.document.reporter.warning('File insertion disabled', line=lineno)] + env = state.document.settings.env + fn = arguments[0] + source_dir = path.dirname(path.abspath(state_machine.input_lines.source( + lineno - state_machine.input_offset - 1))) + fn = path.normpath(path.join(source_dir, fn)) + + try: + with open(fn) as f: + text = f.read() + except (IOError, OSError): + retnode = state.document.reporter.warning('Include file %r not found' % + arguments[0], line=lineno) + else: + retnode = nodes.literal_block(text, text, source=fn) + retnode.line = 1 + return [retnode] + +literalinclude_directive.content = 0 +literalinclude_directive.arguments = (1, 0, 0) +directives.register_directive('literalinclude', literalinclude_directive)