Replace .. include by a new .. literalinclude which doesn't raise if the file isn't found.

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`,

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,
+``literalinclude`` directive. [1]_ For example, to include the Python source file
-to include the Python source file :file:`example.py`, use::
+:file:`example.py`, use::
 
-   .. include:: example.py
+   .. literalinclude:: example.py
-      :literal:
+
+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.

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``

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

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:
 
-
+.. literalinclude:: ../../Parser/Python.asdl
-.. XXX includefile ../../Parser/Python.asdl

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

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:
 
-
+.. literalinclude:: ../includes/email-unpack.py
-.. include:: ../includes/email-unpack.py
-   :literal:
 
 
 .. 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.
 

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

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
+   .. literalinclude:: ../includes/sqlite3/complete_statement.py
-      :literal:
 
 
 .. function:: enable_callback_tracebacks(flag)
@@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/md5func.py
-   .. include:: ../includes/sqlite3/md5func.py
-      :literal:
 
 
 .. method:: Connection.create_aggregate(name, num_params, aggregate_class)
@@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/mysumaggr.py
-   .. include:: ../includes/sqlite3/mysumaggr.py
-      :literal:
 
 
 .. 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":
 
-
+   .. literalinclude:: ../includes/sqlite3/collation_reverse.py
-   .. include:: ../includes/sqlite3/collation_reverse.py
-      :literal:
 
    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:
 
-
+   .. literalinclude:: ../includes/sqlite3/row_factory.py
-   .. include:: ../includes/sqlite3/row_factory.py
-      :literal:
 
    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:
 
-
+   .. literalinclude:: ../includes/sqlite3/text_factory.py
-   .. include:: ../includes/sqlite3/text_factory.py
-      :literal:
 
 
 .. 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:
 
-
+   .. literalinclude:: ../includes/sqlite3/execute_1.py
-   .. include:: ../includes/sqlite3/execute_1.py
-      :literal:
 
    This example shows how to use the named style:
 
-
+   .. literalinclude:: ../includes/sqlite3/execute_2.py
-   .. include:: ../includes/sqlite3/execute_2.py
-      :literal:
 
    :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.
 
-
+   .. literalinclude:: ../includes/sqlite3/executemany_1.py
-   .. include:: ../includes/sqlite3/executemany_1.py
-      :literal:
 
    Here's a shorter example using a generator:
 
-
+   .. literalinclude:: ../includes/sqlite3/executemany_2.py
-   .. include:: ../includes/sqlite3/executemany_2.py
-      :literal:
 
 
 .. method:: Cursor.executescript(sql_script)
@@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/executescript.py
-   .. include:: ../includes/sqlite3/executescript.py
-      :literal:
 
 
 .. 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`.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_point_1.py
-.. include:: ../includes/sqlite3/adapter_point_1.py
-   :literal:
 
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_point_2.py
-.. include:: ../includes/sqlite3/adapter_point_2.py
-   :literal:
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_datetime.py
-.. include:: ../includes/sqlite3/adapter_datetime.py
-   :literal:
 
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/converter_point.py
-.. include:: ../includes/sqlite3/converter_point.py
-   :literal:
 
 
 Default adapters and converters
@@ -651,9 +622,7 @@ experimental SQLite date/time functions.
 
 The following example demonstrates this.
 
-
+.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
-.. include:: ../includes/sqlite3/pysqlite_datetime.py
-   :literal:
 
 
 .. _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.
 
-
+.. literalinclude:: ../includes/sqlite3/shortcut_methods.py
-.. include:: ../includes/sqlite3/shortcut_methods.py
-   :literal:
 
 
 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:
 
-
+.. literalinclude:: ../includes/sqlite3/rowclass.py
-.. include:: ../includes/sqlite3/rowclass.py
-   :literal:
 

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.
 
-
+.. literalinclude:: ../includes/minidom-example.py
-.. include:: ../includes/minidom-example.py
-   :literal:
 
 
 .. _minidom-and-dom:

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`,

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,
+``literalinclude`` directive. [1]_ For example, to include the Python source file
-to include the Python source file :file:`example.py`, use::
+:file:`example.py`, use::
 
-   .. include:: example.py
+   .. literalinclude:: example.py
-      :literal:
+
+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.

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``

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

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

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:
 
-
+.. literalinclude:: ../includes/email-unpack.py
-.. include:: ../includes/email-unpack.py
-   :literal:
 
 
 .. 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.
 

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

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
+   .. literalinclude:: ../includes/sqlite3/complete_statement.py
-      :literal:
 
 
 .. function:: enable_callback_tracebacks(flag)
@@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/md5func.py
-   .. include:: ../includes/sqlite3/md5func.py
-      :literal:
 
 
 .. method:: Connection.create_aggregate(name, num_params, aggregate_class)
@@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/mysumaggr.py
-   .. include:: ../includes/sqlite3/mysumaggr.py
-      :literal:
 
 
 .. 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":
 
-
+   .. literalinclude:: ../includes/sqlite3/collation_reverse.py
-   .. include:: ../includes/sqlite3/collation_reverse.py
-      :literal:
 
    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:
 
-
+   .. literalinclude:: ../includes/sqlite3/row_factory.py
-   .. include:: ../includes/sqlite3/row_factory.py
-      :literal:
 
    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:
 
-
+   .. literalinclude:: ../includes/sqlite3/text_factory.py
-   .. include:: ../includes/sqlite3/text_factory.py
-      :literal:
 
 
 .. 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:
 
-
+   .. literalinclude:: ../includes/sqlite3/execute_1.py
-   .. include:: ../includes/sqlite3/execute_1.py
-      :literal:
 
    This example shows how to use the named style:
 
-
+   .. literalinclude:: ../includes/sqlite3/execute_2.py
-   .. include:: ../includes/sqlite3/execute_2.py
-      :literal:
 
    :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.
 
-
+   .. literalinclude:: ../includes/sqlite3/executemany_1.py
-   .. include:: ../includes/sqlite3/executemany_1.py
-      :literal:
 
    Here's a shorter example using a generator:
 
-
+   .. literalinclude:: ../includes/sqlite3/executemany_2.py
-   .. include:: ../includes/sqlite3/executemany_2.py
-      :literal:
 
 
 .. method:: Cursor.executescript(sql_script)
@@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods:
 
    Example:
 
-
+   .. literalinclude:: ../includes/sqlite3/executescript.py
-   .. include:: ../includes/sqlite3/executescript.py
-      :literal:
 
 
 .. 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`.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_point_1.py
-.. include:: ../includes/sqlite3/adapter_point_1.py
-   :literal:
 
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_point_2.py
-.. include:: ../includes/sqlite3/adapter_point_2.py
-   :literal:
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/adapter_datetime.py
-.. include:: ../includes/sqlite3/adapter_datetime.py
-   :literal:
 
 
 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.
 
-
+.. literalinclude:: ../includes/sqlite3/converter_point.py
-.. include:: ../includes/sqlite3/converter_point.py
-   :literal:
 
 
 Default adapters and converters
@@ -651,9 +622,7 @@ experimental SQLite date/time functions.
 
 The following example demonstrates this.
 
-
+.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
-.. include:: ../includes/sqlite3/pysqlite_datetime.py
-   :literal:
 
 
 .. _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.
 
-
+.. literalinclude:: ../includes/sqlite3/shortcut_methods.py
-.. include:: ../includes/sqlite3/shortcut_methods.py
-   :literal:
 
 
 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:
 
-
+.. literalinclude:: ../includes/sqlite3/rowclass.py
-.. include:: ../includes/sqlite3/rowclass.py
-   :literal:
 

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.
 
-
+.. literalinclude:: ../includes/minidom-example.py
-.. include:: ../includes/minidom-example.py
-   :literal:
 
 
 .. _minidom-and-dom:

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',
+directives.register_directive('highlightlang', highlightlang_directive)
-                              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)