Merge branch '3.x'

12 files changed, 78 insertions, 21 deletions

diff --git a/doc/_static/translation.png b/doc/_static/translation.png
index aa5c5f018..002b3d1f3 100644
--- a/doc/_static/translation.png
+++ b/doc/_static/translation.png
diff --git a/doc/_static/translation.puml b/doc/_static/translation.puml
index 5c3a7350b..7b8fc9f59 100644
--- a/doc/_static/translation.puml
+++ b/doc/_static/translation.puml
@@ -12,5 +12,5 @@ SphinxProject -r-> .rst
 .pot -r-> .po : Pootle
 .po -d-> .mo : msgfmt
 .mo -l-> TranslatedBuild
-.rst -d-> TranslatedBuild : "sphinx-buid -Dlanguage="
+.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage="
 @enduml
diff --git a/doc/_static/translation.svg b/doc/_static/translation.svg
index 74b78a1e7..4e3ab5ab4 100644
--- a/doc/_static/translation.svg
+++ b/doc/_static/translation.svg
@@ -1,4 +1,18 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="224px" preserveAspectRatio="none" style="width:602px;height:224px;" version="1.1" viewBox="0 0 602 224" width="602px" zoomAndPan="magnify"><defs><filter height="300%" id="f7a11izs19byb" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><!--entity SphinxProject--><polygon fill="#FEFECE" filter="url(#f7a11izs19byb)" points="6,31.5,6,67.5986,112,67.5986,112,41.5,102,31.5,6,31.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M102,31.5 L102,41.5 L112,41.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="86" x="16" y="54.6318">SphinxProject</text><!--entity .rst--><polygon fill="#FEFECE" filter="url(#f7a11izs19byb)" points="147,31.5,147,67.5986,187,67.5986,187,41.5,177,31.5,147,31.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M177,31.5 L177,41.5 L187,41.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="20" x="157" y="54.6318">.rst</text><!--entity .pot--><path d="M337,37 C337,27 359,27 359,27 C359,27 381,27 381,37 L381,62.0986 C381,72.0986 359,72.0986 359,72.0986 C359,72.0986 337,72.0986 337,62.0986 L337,37 " fill="#FEFECE" filter="url(#f7a11izs19byb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M337,37 C337,47 359,47 359,47 C359,47 381,47 381,37 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="24" x="347" y="64.1318">.pot</text><!--entity .po--><path d="M455,37 C455,27 475,27 475,27 C475,27 495,27 495,37 L495,62.0986 C495,72.0986 475,72.0986 475,72.0986 C475,72.0986 455,72.0986 455,62.0986 L455,37 " fill="#FEFECE" filter="url(#f7a11izs19byb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M455,37 C455,47 475,47 475,47 C475,47 495,47 495,37 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="20" x="465" y="64.1318">.po</text><!--entity .mo--><path d="M373.5,177 C373.5,167 395,167 395,167 C395,167 416.5,167 416.5,177 L416.5,202.0986 C416.5,212.0986 395,212.0986 395,212.0986 C395,212.0986 373.5,212.0986 373.5,202.0986 L373.5,177 " fill="#FEFECE" filter="url(#f7a11izs19byb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M373.5,177 C373.5,187 395,187 395,187 C395,187 416.5,187 416.5,177 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="23" x="383.5" y="204.1318">.mo</text><!--entity translator--><ellipse cx="560" cy="18" fill="#FEFECE" filter="url(#f7a11izs19byb)" rx="8" ry="8" style="stroke: #A80036; stroke-width: 2.0;"/><path d="M560,26 L560,53 M547,34 L573,34 M560,53 L547,68 M560,53 L573,68 " fill="none" filter="url(#f7a11izs19byb)" style="stroke: #A80036; stroke-width: 2.0;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="60" x="530" y="88.1318">translator</text><!--entity TranslatedBuild--><polygon fill="#FEFECE" filter="url(#f7a11izs19byb)" points="202.5,171.5,202.5,207.5986,321.5,207.5986,321.5,181.5,311.5,171.5,202.5,171.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M311.5,171.5 L311.5,181.5 L321.5,181.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="99" x="212.5" y="194.6318">TranslatedBuild</text><!--link .po to translator--><path d="M500.3972,49.5 C510.2325,49.5 520.0678,49.5 529.9032,49.5 " fill="none" id=".po-translator" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="495.2539,49.5,504.2539,53.5,500.2539,49.5,504.2539,45.5,495.2539,49.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--link SphinxProject to .rst--><path d="M112.1563,49.5 C122.0076,49.5 131.859,49.5 141.7104,49.5 " fill="none" id="SphinxProject-.rst" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="146.8621,49.5,137.8621,45.5,141.8621,49.5,137.8621,53.5,146.8621,49.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--link .rst to .pot--><path d="M187.1845,49.5 C221.8302,49.5 292.6458,49.5 331.676,49.5 " fill="none" id=".rst-.pot" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="336.7347,49.5,327.7347,45.5,331.7347,49.5,327.7347,53.5,336.7347,49.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="113" x="205.5" y="43.6938">sphinx-build gettext</text><!--link .pot to .po--><path d="M381.0918,49.5 C400.726,49.5 429.4114,49.5 449.9055,49.5 " fill="none" id=".pot-.po" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="454.9288,49.5,445.9288,45.5,449.9288,49.5,445.9288,53.5,454.9288,49.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="37" x="399.5" y="43.6938">Pootle</text><!--link .po to .mo--><path d="M461.9686,72.305 C447.9056,96.9151 425.5182,136.0932 410.5467,162.2933 " fill="none" id=".po-.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="408.0259,166.7048,415.9642,160.8753,410.5066,162.3636,409.0183,156.9061,408.0259,166.7048" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="43" x="434" y="134.1938">msgfmt</text><!--link TranslatedBuild to .mo--><path d="M326.9772,189.5 C342.4024,189.5 357.8276,189.5 373.2527,189.5 " fill="none" id="TranslatedBuild-.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="321.7461,189.5,330.7461,193.5,326.7461,189.5,330.7461,185.5,321.7461,189.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--link .rst to TranslatedBuild--><path d="M179.2251,67.5159 C196.4449,92.8925 227.8341,139.1503 246.6178,166.8315 " fill="none" id=".rst-TranslatedBuild" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="249.5202,171.1086,247.7765,161.4153,246.7127,166.9712,241.1568,165.9074,249.5202,171.1086" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="143" x="227" y="134.1938">sphinx-buid -Dlanguage=</text><!--
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="223px" preserveAspectRatio="none" style="width:637px;height:223px;" version="1.1" viewBox="0 0 637 223" width="637px" zoomAndPan="magnify"><defs><filter height="300%" id="fh7abla96c8rb" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><!--MD5=[631d54569d64dd7be7afb1602a233020]
+entity SphinxProject--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="6,30.5,6,66.7969,120,66.7969,120,40.5,110,30.5,6,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M110,30.5 L110,40.5 L120,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="94" x="16" y="53.4951">SphinxProject</text><!--MD5=[61096c0d57626e43fed95496d4441932]
+entity .rst--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="155,30.5,155,66.7969,197,66.7969,197,40.5,187,30.5,155,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M187,30.5 L187,40.5 L197,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="165" y="53.4951">.rst</text><!--MD5=[08ed079d9b091f9ed2d220f9f6abc033]
+entity .pot--><path d="M359.5,36 C359.5,26 383,26 383,26 C383,26 406.5,26 406.5,36 L406.5,61.2969 C406.5,71.2969 383,71.2969 383,71.2969 C383,71.2969 359.5,71.2969 359.5,61.2969 L359.5,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M359.5,36 C359.5,46 383,46 383,46 C383,46 406.5,46 406.5,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="27" x="369.5" y="62.9951">.pot</text><!--MD5=[66eca29884632d3929c321eae20b9288]
+entity .po--><path d="M483,36 C483,26 504,26 504,26 C504,26 525,26 525,36 L525,61.2969 C525,71.2969 504,71.2969 504,71.2969 C504,71.2969 483,71.2969 483,61.2969 L483,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M483,36 C483,46 504,46 504,46 C504,46 525,46 525,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="493" y="62.9951">.po</text><!--MD5=[fad5092d1b513ed9e4cd2391fb0fb212]
+entity .mo--><path d="M398,176 C398,166 421,166 421,166 C421,166 444,166 444,176 L444,201.2969 C444,211.2969 421,211.2969 421,211.2969 C421,211.2969 398,211.2969 398,201.2969 L398,176 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M398,176 C398,186 421,186 421,186 C421,186 444,186 444,176 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="26" x="408" y="202.9951">.mo</text><!--MD5=[8f276d451ff344d4b5b89d896332ffcd]
+entity translator--><ellipse cx="593" cy="17.5" fill="#FEFECE" filter="url(#fh7abla96c8rb)" rx="8" ry="8" style="stroke: #A80036; stroke-width: 1.5;"/><path d="M593,25.5 L593,52.5 M580,33.5 L606,33.5 M593,52.5 L580,67.5 M593,52.5 L606,67.5 " fill="none" filter="url(#fh7abla96c8rb)" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="65" x="560.5" y="85.9951">translator</text><!--MD5=[ba0f3816bcb6df458d88626e193b44ee]
+entity TranslatedBuild--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="214.5,170.5,214.5,206.7969,341.5,206.7969,341.5,180.5,331.5,170.5,214.5,170.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M331.5,170.5 L331.5,180.5 L341.5,180.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="107" x="224.5" y="193.4951">TranslatedBuild</text><!--MD5=[2a0f0d8c54238b3eb600ae284aca39d2]
+reverse link .po to translator--><path d="M530.44,48.5 C540.43,48.5 550.43,48.5 560.43,48.5 " fill="none" id=".po&lt;-translator" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="525.21,48.5,534.21,52.5,530.21,48.5,534.21,44.5,525.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[25ad71f3d3609323ec521914d1dc498d]
+link SphinxProject to .rst--><path d="M120.38,48.5 C130.13,48.5 139.87,48.5 149.61,48.5 " fill="none" id="SphinxProject-&gt;.rst" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="154.71,48.5,145.71,44.5,149.71,48.5,145.71,52.5,154.71,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[1109e8764a7297dc8aca732b1794aa90]
+link .rst to .pot--><path d="M197.37,48.5 C234.72,48.5 311.88,48.5 354,48.5 " fill="none" id=".rst-&gt;.pot" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="359.21,48.5,350.21,44.5,354.21,48.5,350.21,52.5,359.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="126" x="215.25" y="41.5669">sphinx-build gettext</text><!--MD5=[c2d0ba229470f335ea07ab2ed6b28ec0]
+link .pot to .po--><path d="M406.62,48.5 C427.03,48.5 456.51,48.5 477.68,48.5 " fill="none" id=".pot-&gt;.po" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="482.87,48.5,473.87,44.5,477.87,48.5,473.87,52.5,482.87,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="40" x="424.75" y="41.5669">Pootle</text><!--MD5=[06651b5914fbf4764a077bbac7efe19a]
+link .po to .mo--><path d="M491.03,71.06 C476.38,95.43 452.52,135.09 436.8,161.24 " fill="none" id=".po-&gt;.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="434.15,165.63,442.2104,159.9705,436.7225,161.3425,435.3505,155.8546,434.15,165.63" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="50" x="462" y="132.0669">msgfmt</text><!--MD5=[02fa75427086f2cebad4a5f1b2dd96dd]
+reverse link TranslatedBuild to .mo--><path d="M346.94,188.5 C363.88,188.5 380.82,188.5 397.76,188.5 " fill="none" id="TranslatedBuild&lt;-.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="341.68,188.5,350.68,192.5,346.68,188.5,350.68,184.5,341.68,188.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[e72b6258a50343d4926d984a36170cf2]
+link .rst to TranslatedBuild--><path d="M188.71,66.7 C207.27,91.8 241.75,138.46 262,165.86 " fill="none" id=".rst-&gt;TranslatedBuild" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="265.13,170.08,262.9905,160.4663,262.1552,166.0612,256.5604,165.226,265.13,170.08" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="165" x="241" y="132.0669">sphinx-build -Dlanguage=</text><!--MD5=[30dba34f254541587149d90abdb00688]
 @startuml

 file "SphinxProject"

 file ".rst"

@@ -13,17 +27,16 @@ SphinxProject -r-> .rst
 .pot -r-> .po : Pootle

 .po -d-> .mo : msgfmt

 .mo -l-> TranslatedBuild

-.rst -d-> TranslatedBuild : "sphinx-buid -Dlanguage="

+.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage="

 @enduml

 
-PlantUML version 1.2018.13(Mon Nov 26 18:11:51 CET 2018)
+PlantUML version 1.2020.00(Sat Jan 11 12:30:53 GMT 2020)
 (GPL source distribution)
 Java Runtime: OpenJDK Runtime Environment
 JVM: OpenJDK 64-Bit Server VM
-Java Version: 11.0.6+10-post-Ubuntu-1ubuntu119.10.1
+Java Version: 1.8.0_252-b09
 Operating System: Linux
-OS Version: 5.3.0-40-generic
 Default Encoding: UTF-8
 Language: en
-Country: US
+Country: null
 --></g></svg>
\ No newline at end of file
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index cdb609669..27dc57e9a 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -56,6 +56,16 @@ The following is a list of deprecated interfaces.
      - 6.0
      - ``docutils.utils.smartyquotes``
 
+   * - ``sphinx.ext.autodoc.members_set_option()``
+     - 3.2
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.merge_special_members_option()``
+     - 3.2
+     - 5.0
+     - ``sphinx.ext.autodoc.merge_members_option()``
+
    * - ``sphinx.writers.texinfo.TexinfoWriter.desc``
      - 3.2
      - 5.0
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
index 7da16ed1e..2407e3be7 100644
--- a/doc/man/sphinx-quickstart.rst
+++ b/doc/man/sphinx-quickstart.rst
@@ -20,7 +20,7 @@ Options
 
 .. option:: -q, --quiet
 
-   Quiet mode that will skip interactive wizard to specify options.
+   Quiet mode that skips the interactive wizard for specifying options.
    This option requires `-p`, `-a` and `-v` options.
 
 .. option:: -h, --help, --version
diff --git a/doc/templating.rst b/doc/templating.rst
index 0e3815c29..548f8b8d9 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -7,7 +7,7 @@ Templating
 ==========
 
 Sphinx uses the `Jinja <http://jinja.pocoo.org>`_ templating engine for its HTML
-templates.  Jinja is a text-based engine, and inspired by Django templates, so
+templates.  Jinja is a text-based engine, inspired by Django templates, so
 anyone having used Django will already be familiar with it.  It also has
 excellent documentation for those who need to make themselves familiar with it.
 
diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
index fb4f289b4..67d5e10e5 100644
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -6,8 +6,8 @@ Internationalization
 .. versionadded:: 1.1
 
 Complementary to translations provided for Sphinx-generated messages such as
-navigation bars, Sphinx provides mechanisms facilitating *document* translations
-in itself.  See the :ref:`intl-options` for details on configuration.
+navigation bars, Sphinx provides mechanisms facilitating the translation of
+*documents*.  See the :ref:`intl-options` for details on configuration.
 
 .. figure:: /_static/translation.*
    :width: 100%
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 309d6e700..7e996117f 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -823,6 +823,8 @@ documentation on :ref:`intl` for details.
      extension, e.g. ``dirname/filename``
    * ``{path}`` - the directory path component of the filename, with a trailing
      slash if non-empty, e.g. ``dirname/``
+   * ``{docpath}`` - the directory path component for the current document, with
+     a trailing slash if non-empty.
    * ``{basename}`` - the filename without the directory path or file extension
      components, e.g. ``filename``
    * ``{ext}`` - the file extension, e.g. ``.png``
@@ -836,6 +838,9 @@ documentation on :ref:`intl` for details.
    .. versionchanged:: 1.5
       Added ``{path}`` and ``{basename}`` tokens.
 
+   .. versionchanged:: 3.2
+      Added ``{docpath}`` token.
+
 
 .. _math-options:
 
@@ -915,7 +920,7 @@ that use Sphinx's HTMLWriter class.
 
 .. confval:: html_short_title
 
-   A shorter "title" for the HTML docs.  This is used in for links in the
+   A shorter "title" for the HTML docs.  This is used for links in the
    header and in the HTML Help docs.  If not given, it defaults to the value of
    :confval:`html_title`.
 
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 150b62c4d..71f49c240 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -136,9 +136,22 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
            :undoc-members:
 
    * "Private" members (that is, those named like ``_private`` or ``__private``)
-     will be included if the ``private-members`` flag option is given.
+     will be included if the ``private-members`` flag option is given::
+
+        .. automodule:: noodle
+           :members:
+           :private-members:
+
+     It can also take an explicit list of member names to be documented as
+     arguments::
+
+        .. automodule:: noodle
+           :members:
+           :private-members: _spicy, _garlickly
 
      .. versionadded:: 1.1
+     .. versionchanged:: 3.2
+        The option can now take arguments.
 
    * autodoc considers a member private if its docstring contains
      ``:meta private:`` in its :ref:`info-field-lists`.
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
index 33d6cf016..0fe9b535d 100644
--- a/doc/usage/extensions/doctest.rst
+++ b/doc/usage/extensions/doctest.rst
@@ -67,7 +67,7 @@ a comma-separated list of group names.
    default set of flags is specified by the :confval:`doctest_default_flags`
    configuration variable.
 
-   This directive supports three options:
+   This directive supports five options:
 
    * ``hide``, a flag option, hides the doctest block in other builders.  By
      default it is shown as a highlighted doctest block.
@@ -102,6 +102,11 @@ a comma-separated list of group names.
 
         Supported PEP-440 operands and notations
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
    signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
    when building presentation output (HTML, LaTeX etc.).
@@ -119,11 +124,16 @@ a comma-separated list of group names.
 
    A code block for a code-output-style test.
 
-   This directive supports one option:
+   This directive supports three options:
 
    * ``hide``, a flag option, hides the code block in other builders.  By
      default it is shown as a highlighted code block.
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    .. note::
 
       Code in a ``testcode`` block is always executed all at once, no matter how
@@ -149,7 +159,7 @@ a comma-separated list of group names.
    The corresponding output, or the exception message, for the last
    :rst:dir:`testcode` block.
 
-   This directive supports two options:
+   This directive supports four options:
 
    * ``hide``, a flag option, hides the output block in other builders.  By
      default it is shown as a literal block without highlighting.
@@ -157,6 +167,11 @@ a comma-separated list of group names.
    * ``options``, a string option, can be used to give doctest flags
      (comma-separated) just like in normal doctest blocks.
 
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
    Example::
 
       .. testcode::
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index fcdbc3f16..e94106148 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -114,9 +114,9 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Additional options**
 
-   You can use ``caption`` option to provide a toctree caption and you can use
-   ``name`` option to provide implicit target name that can be referenced by
-   using :rst:role:`ref`::
+   You can use the ``caption`` option to provide a toctree caption and you can
+   use the ``name`` option to provide an implicit target name that can be
+   referenced by using :rst:role:`ref`::
 
       .. toctree::
          :caption: Table of Contents
@@ -246,7 +246,7 @@ The special document names (and pages generated for them) are:
 
 * every name beginning with ``_``
 
-  Though only few such names are currently used by Sphinx, you should not
+  Though few such names are currently used by Sphinx, you should not
   create documents or document-containing directories with such names.  (Using
   ``_`` as a prefix for a custom template directory is fine.)
 
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index e5362b9f0..fb06e8741 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -348,7 +348,7 @@ Third Party Themes
 
 There are many third-party themes available. Some of these are general use,
 while others are specific to an individual project. A section of third-party
-themes is listed below. Many more can be found on PyPI__, GitHub__ and
+themes is listed below. Many more can be found on PyPI__, GitHub__, GitLab__ and
 sphinx-themes.org__.
 
 .. cssclass:: clear
@@ -367,4 +367,5 @@ sphinx-themes.org__.
 
 .. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
 .. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
+.. __: https://gitlab.com/explore?name=sphinx+theme
 .. __: https://sphinx-themes.org/