Do not overflow object cross references

docs/conf.py

@@ -25,6 +25,7 @@
 extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',

docs/demo/api.rst

@@ -137,3 +137,18 @@ Data
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis.
 
 Some data link :data:`Data_item_1`.
+
+
+Sphinx Extensions
+=================
+
+sphinx.ext.autosummary
+----------------------
+
+.. autosummary::
+
+   test_py_module.test.add_numbers
+   test_py_module.test.subtract_numbers
+   test_py_module.test.Foo
+
+

docs/demo/test_py_module/test_py27.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""
+This module will overwrite test.py for Python 2.7 builds.
+Type signatures cause autodoc to break in Python 2.7 documentation builds, so they are removed here.
+
+Test Module for sphinx_rtd_theme."""
+
+
+class Foo:
+
+    """Docstring for class Foo.
+
+    This text tests for the formatting of docstrings generated from output
+    ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the
+    ``<dl>``, and ``<dt>`` tags. Also, ``<tt>`` is used for class, method names
+    and etc, but those will *always* have the ``.descname`` or
+    ``.descclassname`` class.
+
+    Term
+        It is also possible to include definitions inside docstrings.
+        They should be styled as a normal definition list.
+
+    :Field List:
+        It is also possible to include definitions inside docstrings.
+        They should be styled as a normal definition list.
+
+    .. [1] A footnote contains body elements, consistently indented by at
+       least 3 spaces.
+
+    .. [Citation] A citation contains body elements, consistently indented by at
+       least 3 spaces.
+
+    Normal ``<tt>`` (like the <tt> I just wrote here) needs to be shown with
+    the same style as anything else with ````this type of markup````.
+
+    It's common for programmers to give a code example inside of their
+    docstring::
+
+        from test_py_module import Foo
+
+        myclass = Foo()
+        myclass.dothismethod('with this argument')
+        myclass.flush()
+
+        print(myclass)
+
+
+    Here is a link to :py:meth:`capitalize`.
+    Here is a link to :py:meth:`__init__`.
+
+    """
+
+    #: Doc comment for class attribute Foo.bar.
+    #: It can have multiple lines.
+    bar = 1
+
+    flox = 1.5   #: Doc comment for Foo.flox. One line only.
+
+    baz = 2
+    """Docstring for class attribute Foo.baz."""
+
+    def __init__(self, qux, spam=False):
+        """Start the Foo.
+
+        :param qux: The first argument to initialize class.
+        :type qux: string
+        :param spam: Spam me yes or no...
+        :type spam: bool
+
+        """
+        #: Doc comment for instance attribute qux.
+        self.qux = 3
+
+        self.spam = 4
+        """Docstring for instance attribute spam."""
+
+    def add(self, val1, val2):
+        """Return the added values.
+
+        :param val1: First number to add.
+        :type val1: int
+        :param val2: Second number to add.
+        :type val2: int
+        :rtype: int
+
+        The parameters of this method are described in the parameter list.
+        """
+
+        return val1 + val2
+
+    def capitalize(self, myvalue):
+        """Return a string as uppercase.
+
+        :param myvalue: String to change
+        :type myvalue: string
+        :rtype: string
+
+        """
+
+        return myvalue.upper()
+
+    def another_function(self, a, b, **kwargs):
+        """
+        Here is another function.
+
+        :param a: The number of green hats you own.
+        :type a: int
+
+        :param b: The number of non-green hats you own.
+        :type b: int
+
+        :param kwargs: Additional keyword arguments. Each keyword parameter
+                       should specify the name of your favorite cuisine.
+                       The values should be floats, specifying the mean price
+                       of your favorite dish in that cooking style.
+        :type kwargs: float
+
+        :returns: A 2-tuple.  The first element is the mean price of all dishes
+                  across cuisines.  The second element is the total number of
+                  hats you own: :math:`a + b`.
+        :rtype: tuple
+
+        :raises ValueError: When ``a`` is not an integer.
+
+        .. versionadded:: 1.0
+            This was added in 1.0
+        .. versionchanged:: 2.0
+            This was changed in 2.0
+        .. deprecated:: 3.0
+            This is deprecated since 3.0
+        """
+        return sum(kwargs.values()) / len(kwargs), a + b
+
+
+def add_numbers(a, b):
+    """Add two numbers together
+
+    :param a: The first number
+    :param b: The second number
+
+    Here is some more text.
+    """
+    return a + b
+
+
+def subtract_numbers(a, b):
+    """Subtract two numbers
+
+    :param a: The first number
+    :param b: The second number
+    """
+    return a - b

src/sass/_theme_rst.sass

@@ -413,6 +413,8 @@
     &.xref, a &
       font-weight: bold
       color: $text-codexref-color
+      // https://github.com/readthedocs/sphinx_rtd_theme/issues/1368
+      overflow-wrap: normal
   pre, kbd, samp
     font-family: $code-font-family
   // If the literal is inside an a tag, let's color it like a link

tox.ini

@@ -7,6 +7,9 @@ envlist =
     py{310}-sphinx{42,43,44,45,50,51,52}{-html4,-html5,latest}{-qa,}
 
 [testenv]
+allowlist_externals =
+    cp
+    rm
 setev =
     LANG=C
 deps =
@@ -49,5 +52,13 @@ deps =
     sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 commands =
     pytest {posargs} tests/
+    # This is a short-term hack to allow us to have a Python 3-specific syntax
+    # and swap it out for a Python 2.7 version while we're building.
+    # This terrible solution is only acceptable because we will remove it again very soon
+    # See: https://github.com/readthedocs/sphinx_rtd_theme/pull/1369
+    py27: cp docs/demo/test_py_module/test.py docs/demo/test_py_module/test_py3.py
+    py27: cp docs/demo/test_py_module/test_py27.py docs/demo/test_py_module/test.py
     !html4: sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
     html4: sphinx-build -b html -Dhtml4_writer=1 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
+    py27: cp docs/demo/test_py_module/test_py3.py docs/demo/test_py_module/test.py
+    py27: rm docs/demo/test_py_module/test_py3.py