Anonymous avatar Anonymous committed 37a25af

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

Comments (0)

Files changed (20)

Doc-26/c-api/newtypes.rst

 :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

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

 
 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

 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.
 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.
 
 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
 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::
    >>> 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. ::
 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

 .. _ast:
 
-*********************
 Abstract Syntax Trees
-*********************
+=====================
 
 .. module:: _ast
 
 
 
 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

Doc-26/library/datetime.rst

 
 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

 
 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.
 

Doc-26/library/exceptions.rst

 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

    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)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/md5func.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/md5func.py
 
 
 .. method:: Connection.create_aggregate(name, num_params, aggregate_class)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/mysumaggr.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/mysumaggr.py
 
 
 .. method:: Connection.create_collation(name, callable)
 
    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::
 
 
    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
 
    See the following example code for illustration:
 
-
-   .. include:: ../includes/sqlite3/text_factory.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/text_factory.py
 
 
 .. attribute:: Connection.total_changes
 
    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
    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)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/executescript.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/executescript.py
 
 
 .. attribute:: Cursor.rowcount
 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
    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
 
 The following example illustrates both approaches.
 
-
-.. include:: ../includes/sqlite3/converter_point.py
-   :literal:
+.. literalinclude:: ../includes/sqlite3/converter_point.py
 
 
 Default adapters and converters
 
 The following example demonstrates this.
 
-
-.. include:: ../includes/sqlite3/pysqlite_datetime.py
-   :literal:
+.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
 
 
 .. _sqlite3-controlling-transactions:
 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
 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

 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:

Doc-3k/c-api/newtypes.rst

 :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

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

 
 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

 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.
 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.
 
 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
 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::
    >>> 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. ::
 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

 
 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

 
 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.
 

Doc-3k/library/exceptions.rst

 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

    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)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/md5func.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/md5func.py
 
 
 .. method:: Connection.create_aggregate(name, num_params, aggregate_class)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/mysumaggr.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/mysumaggr.py
 
 
 .. method:: Connection.create_collation(name, callable)
 
    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::
 
 
    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
 
    See the following example code for illustration:
 
-
-   .. include:: ../includes/sqlite3/text_factory.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/text_factory.py
 
 
 .. attribute:: Connection.total_changes
 
    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
    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)
 
    Example:
 
-
-   .. include:: ../includes/sqlite3/executescript.py
-      :literal:
+   .. literalinclude:: ../includes/sqlite3/executescript.py
 
 
 .. attribute:: Cursor.rowcount
 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
    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
 
 The following example illustrates both approaches.
 
-
-.. include:: ../includes/sqlite3/converter_point.py
-   :literal:
+.. literalinclude:: ../includes/sqlite3/converter_point.py
 
 
 Default adapters and converters
 
 The following example demonstrates this.
 
-
-.. include:: ../includes/sqlite3/pysqlite_datetime.py
-   :literal:
+.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
 
 
 .. _sqlite3-controlling-transactions:
 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
 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

 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:

sphinx/directives.py

     :copyright: 2007 by Georg Brandl.
     :license: Python license.
 """
+from __future__ import with_statement
 
 import re
 import string
 
 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)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.