Merge pull request #4841 from gussiecarther/doc_rst_prolog_and_rst_epilog

Fix #4420: Docs conflict on use of rst_prolog and rst_epilog

3 files changed, 20 insertions, 8 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 46958cde6..1c8ae48e0 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -192,8 +192,9 @@ General configuration
    .. index:: pair: global; substitutions
 
    A string of reStructuredText that will be included at the end of every source
-   file that is read.  This is the right place to add substitutions that should
-   be available in every file.  An example::
+   file that is read.  This is a possible place to add substitutions that should
+   be available in every file (another being :confval:`rst_prolog`).  An
+   example::
 
       rst_epilog = """
       .. |psf| replace:: Python Software Foundation
@@ -203,8 +204,16 @@ General configuration
 
 .. confval:: rst_prolog
 
+   .. index:: pair: global; substitutions
+
    A string of reStructuredText that will be included at the beginning of every
-   source file that is read.
+   source file that is read.  This is a possible place to add substitutions that
+   should be available in every file (another being :confval:`rst_epilog`).  An
+   example::
+
+      rst_prolog = """
+      .. |psf| replace:: Python Software Foundation
+      """
 
    .. versionadded:: 1.0
 
diff --git a/doc/faq.rst b/doc/faq.rst
index 8798fd5db..270ceb68a 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -23,7 +23,7 @@ How do I...
    Use themes, see :doc:`theming`.
 
 ... add global substitutions or includes?
-   Add them in the :confval:`rst_epilog` config value.
+   Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
 
 ... display the whole TOC tree in the sidebar?
    Use the :data:`toctree` callable in a custom layout template, probably in the
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 9aa8e1ef7..48ffa5ffb 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -508,11 +508,14 @@ or this::
 See the :duref:`reST reference for substitutions <substitution-definitions>`
 for details.
 
+.. index:: ! pair: global; substitutions
+
 If you want to use some substitutions for all documents, put them into
-:confval:`rst_prolog` or put them into a separate file and include it into all
-documents you want to use them in, using the :rst:dir:`include` directive.  (Be
-sure to give the include file a file name extension differing from that of
-other source files, to avoid Sphinx finding it as a standalone document.)
+:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
+and include it into all documents you want to use them in, using the
+:rst:dir:`include` directive.  (Be sure to give the include file a file name
+extension differing from that of other source files, to avoid Sphinx finding it
+as a standalone document.)
 
 Sphinx defines some default substitutions, see :ref:`default-substitutions`.