From 1eae014f30babae14afb41bd9b17bb9a40051b3c Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 19 Mar 2024 22:46:09 -0400 Subject: [PATCH] Footnotes are discouraged (#1290) --- documentation/markup.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index c7a5a5ac4c..dfabcd6668 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -699,7 +699,7 @@ 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 -``literalinclude`` directive. [1]_ For example, to include the Python source +``literalinclude`` directive. For example, to include the Python source file :file:`example.py`, use:: .. literalinclude:: example.py @@ -707,6 +707,13 @@ file :file:`example.py`, use:: The file name is relative to the current file's path. Documentation-specific include files should be placed in the ``Doc/includes`` subdirectory. +.. note:: + + There is a standard ``include`` directive, but it raises errors if the + file is not found. ``literalinclude`` is preferred because it only emits a + warning instead of raising an error. + + .. _rest-inline-markup: .. _roles: @@ -1326,9 +1333,3 @@ default. They are set in the build configuration file :file:`conf.py`. 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.