Merge branch '3.x' into preprocess-other-sections

19 files changed, 208 insertions, 96 deletions

diff --git a/CHANGES b/CHANGES
index d8a3cb915..235e34852 100644
--- a/CHANGES
+++ b/CHANGES
@@ -32,6 +32,8 @@ Features added
 * #7888: napoleon: Add aliases Warn and Raise.
 * #7690: napoleon: parse type strings and make them hyperlinks as possible.  The
   conversion rule can be updated via :confval:`napoleon_type_aliases`
+* #8049: napoleon: Create a hyperlink for each the type of parameter when
+  :confval:`napoleon_use_params` is False
 * C, added :rst:dir:`c:alias` directive for inserting copies
   of existing declarations.
 * #7745: html: inventory is broken if the docname contains a space
@@ -42,6 +44,8 @@ Features added
 * #7768: i18n: :confval:`figure_language_filename` supports ``docpath`` token
 * #5208: linkcheck: Support checks for local links
 * #5090: setuptools: Link verbosity to distutils' -v and -q option
+* #6698: doctest: Add ``:trim-doctest-flags:`` and ``:no-trim-doctest-flags:``
+  options to doctest, testcode and testoutput directives
 * #7052: add ``:noindexentry:`` to the Python, C, C++, and Javascript domains.
   Update the documentation to better reflect the relationship between this option
   and the ``:noindex:`` option.
@@ -75,6 +79,7 @@ Bugs fixed
 * #7940: apidoc: An extra newline is generated at the end of the rst file if a
   module has submodules 
 * #4258: napoleon: decorated special methods are not shown
+* #7799: napoleon: parameters are not escaped for combined params in numpydoc
 * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links
 * #7846: html theme: XML-invalid files were generated
 * #7894: gettext: Wrong source info is shown when using rst_epilog
@@ -92,6 +97,7 @@ Bugs fixed
 * #7993: texinfo: a warning not supporting desc_signature_line node is shown
 * #7869: :rst:role:`abbr` role without an explanation will show the explanation
   from the previous abbr role
+* #8048: graphviz: graphviz.css was copied on building non-HTML document
 * C and C++, removed ``noindex`` directive option as it did
   nothing.
 * #7619: Duplicated node IDs are generated if node has multiple IDs
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/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 550b26e2d..add78326b 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -918,7 +918,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/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/
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index 26966016d..7cd89ad32 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -91,7 +91,7 @@ class TestDirective(SphinxDirective):
                 # convert <BLANKLINE>s to ordinary blank lines for presentation
                 test = code
                 code = blankline_re.sub('', code)
-            if doctestopt_re.search(code):
+            if doctestopt_re.search(code) and 'no-trim-doctest-flags' not in self.options:
                 if not test:
                     test = code
                 code = doctestopt_re.sub('', code)
@@ -151,6 +151,10 @@ class TestDirective(SphinxDirective):
                     line=self.lineno)
         if 'skipif' in self.options:
             node['skipif'] = self.options['skipif']
+        if 'trim-doctest-flags' in self.options:
+            node['trim_flags'] = True
+        elif 'no-trim-doctest-flags' in self.options:
+            node['trim_flags'] = False
         return [node]
 
 
@@ -165,26 +169,32 @@ class TestcleanupDirective(TestDirective):
 class DoctestDirective(TestDirective):
     option_spec = {
         'hide': directives.flag,
+        'no-trim-doctest-flags': directives.flag,
         'options': directives.unchanged,
         'pyversion': directives.unchanged_required,
         'skipif': directives.unchanged_required,
+        'trim-doctest-flags': directives.flag,
     }
 
 
 class TestcodeDirective(TestDirective):
     option_spec = {
         'hide': directives.flag,
+        'no-trim-doctest-flags': directives.flag,
         'pyversion': directives.unchanged_required,
         'skipif': directives.unchanged_required,
+        'trim-doctest-flags': directives.flag,
     }
 
 
 class TestoutputDirective(TestDirective):
     option_spec = {
         'hide': directives.flag,
+        'no-trim-doctest-flags': directives.flag,
         'options': directives.unchanged,
         'pyversion': directives.unchanged_required,
         'skipif': directives.unchanged_required,
+        'trim-doctest-flags': directives.flag,
     }
 
 
diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py
index 4a8dd0a4d..d97a7505e 100644
--- a/sphinx/ext/graphviz.py
+++ b/sphinx/ext/graphviz.py
@@ -385,7 +385,7 @@ def man_visit_graphviz(self: ManualPageTranslator, node: graphviz) -> None:
 
 
 def on_build_finished(app: Sphinx, exc: Exception) -> None:
-    if exc is None:
+    if exc is None and app.builder.format == 'html':
         src = path.join(sphinx.package_dir, 'templates', 'graphviz', 'graphviz.css')
         dst = path.join(app.outdir, '_static')
         copy_asset(src, dst)
diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py
index 6d7406ead..6cab63c9f 100644
--- a/sphinx/ext/napoleon/__init__.py
+++ b/sphinx/ext/napoleon/__init__.py
@@ -239,7 +239,7 @@ class Config:
 
     napoleon_type_aliases : :obj:`dict` (Defaults to None)
         Add a mapping of strings to string, translating types in numpy
-        style docstrings. Only works when ``napoleon_use_param = True``.
+        style docstrings.
 
     napoleon_custom_sections : :obj:`list` (Defaults to None)
         Add a list of custom sections to include, expanding the list of parsed sections.
diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py
index 8e9e4d3d6..05b96d3e2 100644
--- a/sphinx/ext/napoleon/docstring.py
+++ b/sphinx/ext/napoleon/docstring.py
@@ -22,12 +22,13 @@ from sphinx.ext.napoleon.iterators import modify_iter
 from sphinx.locale import _, __
 from sphinx.util import logging
 
-logger = logging.getLogger(__name__)
-
 if False:
     # For type annotation
     from typing import Type  # for python3.5.1
 
+
+logger = logging.getLogger(__name__)
+
 _directive_regex = re.compile(r'\.\. \S+::')
 _google_section_regex = re.compile(r'^(\s|\w)+:\s*$')
 _google_typed_arg_regex = re.compile(r'\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)')
@@ -958,16 +959,9 @@ def _convert_numpy_type_spec(_type: str, location: str = None, translations: dic
         for token in combined_tokens
     ]
 
-    # don't use the object role if it's not necessary
-    default_translation = (
-        ":class:`%s`"
-        if not all(type_ == "obj" for _, type_ in types)
-        else "%s"
-    )
-
     converters = {
         "literal": lambda x: "``%s``" % x,
-        "obj": lambda x: convert_obj(x, translations, default_translation),
+        "obj": lambda x: convert_obj(x, translations, ":class:`%s`"),
         "control": lambda x: "*%s*" % x,
         "delimiter": lambda x: x,
         "reference": lambda x: x,
@@ -1078,14 +1072,24 @@ class NumpyDocstring(GoogleDocstring):
         super().__init__(docstring, config, app, what, name, obj, options)
 
     def _get_location(self) -> str:
-        filepath = inspect.getfile(self._obj) if self._obj is not None else ""
+        filepath = inspect.getfile(self._obj) if self._obj is not None else None
         name = self._name
 
         if filepath is None and name is None:
             return None
+        elif filepath is None:
+            filepath = ""
 
         return ":".join([filepath, "docstring of %s" % name])
 
+    def _escape_args_and_kwargs(self, name: str) -> str:
+        func = super()._escape_args_and_kwargs
+
+        if ", " in name:
+            return ", ".join(func(param) for param in name.split(", "))
+        else:
+            return func(name)
+
     def _consume_field(self, parse_type: bool = True, prefer_type: bool = False
                        ) -> Tuple[str, str, List[str]]:
         line = next(self._line_iter)
@@ -1099,12 +1103,11 @@ class NumpyDocstring(GoogleDocstring):
         if prefer_type and not _type:
             _type, _name = _name, _type
 
-        if self._config.napoleon_use_param:
-            _type = _convert_numpy_type_spec(
-                _type,
-                location=self._get_location(),
-                translations=self._config.napoleon_type_aliases or {},
-            )
+        _type = _convert_numpy_type_spec(
+            _type,
+            location=self._get_location(),
+            translations=self._config.napoleon_type_aliases or {},
+        )
 
         indent = self._get_indent(line) + 1
         _desc = self._dedent(self._consume_indented_block(indent))
diff --git a/sphinx/transforms/post_transforms/code.py b/sphinx/transforms/post_transforms/code.py
index add35647b..2012d6e11 100644
--- a/sphinx/transforms/post_transforms/code.py
+++ b/sphinx/transforms/post_transforms/code.py
@@ -9,10 +9,10 @@
 """
 
 import sys
-from typing import Any, Dict, List, NamedTuple, Union
+from typing import Any, Dict, List, NamedTuple
 
 from docutils import nodes
-from docutils.nodes import Node
+from docutils.nodes import Node, TextElement
 from pygments.lexers import PythonConsoleLexer, guess_lexer
 
 from sphinx import addnodes
@@ -93,9 +93,6 @@ class TrimDoctestFlagsTransform(SphinxTransform):
     default_priority = HighlightLanguageTransform.default_priority + 1
 
     def apply(self, **kwargs: Any) -> None:
-        if not self.config.trim_doctest_flags:
-            return
-
         for lbnode in self.document.traverse(nodes.literal_block):  # type: nodes.literal_block
             if self.is_pyconsole(lbnode):
                 self.strip_doctest_flags(lbnode)
@@ -103,8 +100,10 @@ class TrimDoctestFlagsTransform(SphinxTransform):
         for dbnode in self.document.traverse(nodes.doctest_block):  # type: nodes.doctest_block
             self.strip_doctest_flags(dbnode)
 
-    @staticmethod
-    def strip_doctest_flags(node: Union[nodes.literal_block, nodes.doctest_block]) -> None:
+    def strip_doctest_flags(self, node: TextElement) -> None:
+        if not node.get('trim_flags', self.config.trim_doctest_flags):
+            return
+
         source = node.rawsource
         source = doctest.blankline_re.sub('', source)
         source = doctest.doctestopt_re.sub('', source)
diff --git a/tests/roots/test-trim_doctest_flags/index.rst b/tests/roots/test-trim_doctest_flags/index.rst
index 63ce234cd..d63251a5a 100644
--- a/tests/roots/test-trim_doctest_flags/index.rst
+++ b/tests/roots/test-trim_doctest_flags/index.rst
@@ -22,7 +22,19 @@ test-trim_doctest_flags
    >>> datetime.date.now()   # doctest: +QUX
    datetime.date(2008, 1, 1)
 
-.. doctest_block::
+.. doctest::
 
    >>> datetime.date.now()   # doctest: +QUUX
    datetime.date(2008, 1, 1)
+
+.. doctest::
+   :trim-doctest-flags:
+
+   >>> datetime.date.now()   # doctest: +CORGE
+   datetime.date(2008, 1, 1)
+
+.. doctest::
+   :no-trim-doctest-flags:
+
+   >>> datetime.date.now()   # doctest: +GRAULT
+   datetime.date(2008, 1, 1)
diff --git a/tests/test_ext_napoleon_docstring.py b/tests/test_ext_napoleon_docstring.py
index d8ad64b96..9613e57d7 100644
--- a/tests/test_ext_napoleon_docstring.py
+++ b/tests/test_ext_napoleon_docstring.py
@@ -16,6 +16,8 @@ from inspect import cleandoc
 from textwrap import dedent
 from unittest import TestCase, mock
 
+import pytest
+
 from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from sphinx.ext.napoleon.docstring import (
@@ -64,19 +66,19 @@ Sample namedtuple subclass
 
    Quick description of attr1
 
-   :type: Arbitrary type
+   :type: :class:`Arbitrary type`
 
 .. attribute:: attr2
 
    Quick description of attr2
 
-   :type: Another arbitrary type
+   :type: :class:`Another arbitrary type`
 
 .. attribute:: attr3
 
    Adds a newline after the type
 
-   :type: Type
+   :type: :class:`Type`
 """
 
         self.assertEqual(expected, actual)
@@ -1124,7 +1126,7 @@ class NumpyDocstringTest(BaseDocstringTest):
         """
         Single line summary
 
-        :Parameters: **arg1** (*str*) -- Extended
+        :Parameters: **arg1** (:class:`str`) -- Extended
                      description of arg1
         """
     ), (
@@ -1152,14 +1154,14 @@ class NumpyDocstringTest(BaseDocstringTest):
         """
         Single line summary
 
-        :Parameters: * **arg1** (*str*) -- Extended
+        :Parameters: * **arg1** (:class:`str`) -- Extended
                        description of arg1
-                     * **arg2** (*int*) -- Extended
+                     * **arg2** (:class:`int`) -- Extended
                        description of arg2
 
-        :Keyword Arguments: * **kwarg1** (*str*) -- Extended
+        :Keyword Arguments: * **kwarg1** (:class:`str`) -- Extended
                               description of kwarg1
-                            * **kwarg2** (*int*) -- Extended
+                            * **kwarg2** (:class:`int`) -- Extended
                               description of kwarg2
         """
     ), (
@@ -1210,7 +1212,7 @@ class NumpyDocstringTest(BaseDocstringTest):
         """
         Single line summary
 
-        :Parameters: * **arg1** (*str*) -- Extended description of arg1
+        :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1
                      * **\\*args** -- Variable length argument list.
                      * **\\*\\*kwargs** -- Arbitrary keyword arguments.
         """
@@ -1218,6 +1220,23 @@ class NumpyDocstringTest(BaseDocstringTest):
         """
         Single line summary
 
+        Parameters
+        ----------
+        arg1:str
+             Extended description of arg1
+        *args, **kwargs:
+            Variable length argument list and arbitrary keyword arguments.
+        """,
+        """
+        Single line summary
+
+        :Parameters: * **arg1** (:class:`str`) -- Extended description of arg1
+                     * **\\*args, \\*\\*kwargs** -- Variable length argument list and arbitrary keyword arguments.
+        """
+    ), (
+        """
+        Single line summary
+
         Yield
         -----
         str
@@ -1332,7 +1351,7 @@ param1 : MyClass instance
         config = Config(napoleon_use_param=False)
         actual = str(NumpyDocstring(docstring, config))
         expected = """\
-:Parameters: **param1** (*MyClass instance*)
+:Parameters: **param1** (:class:`MyClass instance`)
 """
         self.assertEqual(expected, actual)
 
@@ -1340,7 +1359,7 @@ param1 : MyClass instance
         actual = str(NumpyDocstring(dedent(docstring), config))
         expected = """\
 :param param1:
-:type param1: MyClass instance
+:type param1: :class:`MyClass instance`
 """
         self.assertEqual(expected, actual)
 
@@ -1429,7 +1448,7 @@ arg_ : type
 
         expected = """
 :ivar arg_: some description
-:vartype arg_: type
+:vartype arg_: :class:`type`
 """
 
         config = Config(napoleon_use_ivar=True)
@@ -1449,7 +1468,7 @@ arg_ : type
 
         expected = """
 :ivar arg\\_: some description
-:vartype arg\\_: type
+:vartype arg\\_: :class:`type`
 """
 
         config = Config(napoleon_use_ivar=True)
@@ -1894,59 +1913,59 @@ definition_after_normal_text : int
         expected = """One line summary.
 
 :param no_list:
-:type no_list: int
+:type no_list: :class:`int`
 :param one_bullet_empty:
                          *
-:type one_bullet_empty: int
+:type one_bullet_empty: :class:`int`
 :param one_bullet_single_line:
                                - first line
-:type one_bullet_single_line: int
+:type one_bullet_single_line: :class:`int`
 :param one_bullet_two_lines:
                              +   first line
                                  continued
-:type one_bullet_two_lines: int
+:type one_bullet_two_lines: :class:`int`
 :param two_bullets_single_line:
                                 -  first line
                                 -  second line
-:type two_bullets_single_line: int
+:type two_bullets_single_line: :class:`int`
 :param two_bullets_two_lines:
                               * first line
                                 continued
                               * second line
                                 continued
-:type two_bullets_two_lines: int
+:type two_bullets_two_lines: :class:`int`
 :param one_enumeration_single_line:
                                     1.  first line
-:type one_enumeration_single_line: int
+:type one_enumeration_single_line: :class:`int`
 :param one_enumeration_two_lines:
                                   1)   first line
                                        continued
-:type one_enumeration_two_lines: int
+:type one_enumeration_two_lines: :class:`int`
 :param two_enumerations_one_line:
                                   (iii) first line
                                   (iv) second line
-:type two_enumerations_one_line: int
+:type two_enumerations_one_line: :class:`int`
 :param two_enumerations_two_lines:
                                    a. first line
                                       continued
                                    b. second line
                                       continued
-:type two_enumerations_two_lines: int
+:type two_enumerations_two_lines: :class:`int`
 :param one_definition_one_line:
                                 item 1
                                     first line
-:type one_definition_one_line: int
+:type one_definition_one_line: :class:`int`
 :param one_definition_two_lines:
                                  item 1
                                      first line
                                      continued
-:type one_definition_two_lines: int
+:type one_definition_two_lines: :class:`int`
 :param two_definitions_one_line:
                                  item 1
                                      first line
                                  item 2
                                      second line
-:type two_definitions_one_line: int
+:type two_definitions_one_line: :class:`int`
 :param two_definitions_two_lines:
                                   item 1
                                       first line
@@ -1954,14 +1973,14 @@ definition_after_normal_text : int
                                   item 2
                                       second line
                                       continued
-:type two_definitions_two_lines: int
+:type two_definitions_two_lines: :class:`int`
 :param one_definition_blank_line:
                                   item 1
 
                                       first line
 
                                       extra first line
-:type one_definition_blank_line: int
+:type one_definition_blank_line: :class:`int`
 :param two_definitions_blank_lines:
                                     item 1
 
@@ -1974,12 +1993,12 @@ definition_after_normal_text : int
                                         second line
 
                                         extra second line
-:type two_definitions_blank_lines: int
+:type two_definitions_blank_lines: :class:`int`
 :param definition_after_normal_text: text line
 
                                      item 1
                                          first line
-:type definition_after_normal_text: int
+:type definition_after_normal_text: :class:`int`
 """
         config = Config(napoleon_use_param=True)
         actual = str(NumpyDocstring(docstring, config))
@@ -1987,60 +2006,60 @@ definition_after_normal_text : int
 
         expected = """One line summary.
 
-:Parameters: * **no_list** (*int*)
-             * **one_bullet_empty** (*int*) --
+:Parameters: * **no_list** (:class:`int`)
+             * **one_bullet_empty** (:class:`int`) --
 
                *
-             * **one_bullet_single_line** (*int*) --
+             * **one_bullet_single_line** (:class:`int`) --
 
                - first line
-             * **one_bullet_two_lines** (*int*) --
+             * **one_bullet_two_lines** (:class:`int`) --
 
                +   first line
                    continued
-             * **two_bullets_single_line** (*int*) --
+             * **two_bullets_single_line** (:class:`int`) --
 
                -  first line
                -  second line
-             * **two_bullets_two_lines** (*int*) --
+             * **two_bullets_two_lines** (:class:`int`) --
 
                * first line
                  continued
                * second line
                  continued
-             * **one_enumeration_single_line** (*int*) --
+             * **one_enumeration_single_line** (:class:`int`) --
 
                1.  first line
-             * **one_enumeration_two_lines** (*int*) --
+             * **one_enumeration_two_lines** (:class:`int`) --
 
                1)   first line
                     continued
-             * **two_enumerations_one_line** (*int*) --
+             * **two_enumerations_one_line** (:class:`int`) --
 
                (iii) first line
                (iv) second line
-             * **two_enumerations_two_lines** (*int*) --
+             * **two_enumerations_two_lines** (:class:`int`) --
 
                a. first line
                   continued
                b. second line
                   continued
-             * **one_definition_one_line** (*int*) --
+             * **one_definition_one_line** (:class:`int`) --
 
                item 1
                    first line
-             * **one_definition_two_lines** (*int*) --
+             * **one_definition_two_lines** (:class:`int`) --
 
                item 1
                    first line
                    continued
-             * **two_definitions_one_line** (*int*) --
+             * **two_definitions_one_line** (:class:`int`) --
 
                item 1
                    first line
                item 2
                    second line
-             * **two_definitions_two_lines** (*int*) --
+             * **two_definitions_two_lines** (:class:`int`) --
 
                item 1
                    first line
@@ -2048,14 +2067,14 @@ definition_after_normal_text : int
                item 2
                    second line
                    continued
-             * **one_definition_blank_line** (*int*) --
+             * **one_definition_blank_line** (:class:`int`) --
 
                item 1
 
                    first line
 
                    extra first line
-             * **two_definitions_blank_lines** (*int*) --
+             * **two_definitions_blank_lines** (:class:`int`) --
 
                item 1
 
@@ -2068,7 +2087,7 @@ definition_after_normal_text : int
                    second line
 
                    extra second line
-             * **definition_after_normal_text** (*int*) -- text line
+             * **definition_after_normal_text** (:class:`int`) -- text line
 
                item 1
                    first line
@@ -2230,7 +2249,7 @@ definition_after_normal_text : int
         """)
         expected = dedent("""\
             :param param1: the data to work on
-            :type param1: DataFrame
+            :type param1: :class:`DataFrame`
             :param param2: a parameter with different types
             :type param2: :class:`int` or :class:`float` or :obj:`None`, *optional*
             :param param3: a optional mapping
@@ -2259,6 +2278,7 @@ definition_after_normal_text : int
         actual = str(NumpyDocstring(docstring, config))
         self.assertEqual(expected, actual)
 
+
 @contextmanager
 def warns(warning, match):
     match_re = re.compile(match)
@@ -2293,3 +2313,17 @@ class TestNumpyDocstring:
         for token, error in zip(tokens, errors):
             with warns(warning, match=error):
                 _token_type(token)
+
+    @pytest.mark.parametrize(
+        ("name", "expected"),
+        (
+            ("x, y, z", "x, y, z"),
+            ("*args, **kwargs", r"\*args, \*\*kwargs"),
+            ("*x, **y", r"\*x, \*\*y"),
+        ),
+    )
+    def test_escape_args_and_kwargs(self, name, expected):
+        numpy_docstring = NumpyDocstring("")
+        actual = numpy_docstring._escape_args_and_kwargs(name)
+
+        assert actual == expected
diff --git a/tests/test_transforms_post_transforms_code.py b/tests/test_transforms_post_transforms_code.py
index 880f4711b..2e5da05ae 100644
--- a/tests/test_transforms_post_transforms_code.py
+++ b/tests/test_transforms_post_transforms_code.py
@@ -19,6 +19,23 @@ def test_trim_doctest_flags_html(app, status, warning):
     assert 'BAZ' not in result
     assert 'QUX' not in result
     assert 'QUUX' not in result
+    assert 'CORGE' not in result
+    assert 'GRAULT' in result
+
+
+@pytest.mark.sphinx('html', testroot='trim_doctest_flags',
+                    confoverrides={'trim_doctest_flags': False})
+def test_trim_doctest_flags_disabled(app, status, warning):
+    app.build()
+
+    result = (app.outdir / 'index.html').read_text()
+    assert 'FOO' in result
+    assert 'BAR' in result
+    assert 'BAZ' in result
+    assert 'QUX' in result
+    assert 'QUUX' not in result
+    assert 'CORGE' not in result
+    assert 'GRAULT' in result
 
 
 @pytest.mark.sphinx('latex', testroot='trim_doctest_flags')
@@ -31,3 +48,5 @@ def test_trim_doctest_flags_latex(app, status, warning):
     assert 'BAZ' not in result
     assert 'QUX' not in result
     assert 'QUUX' not in result
+    assert 'CORGE' not in result
+    assert 'GRAULT' in result