Do not overflow object cross references (#1369)

* Do not overflow object cross references

* Rebuild theme for #1369

* Adds a demo for the regression

* Mock sphinx-automodapi for now, but we can use it soon

* we can replace sphinx-automodapi demo entirely with autosummary since it uses this under the hood

* We need a python 2.7 compliant test module. Add a short-term workaround until this is removed in 2.0.

* Add comment about the terrible tox workaround

* Use a less hacky way of conditional autosummary in demo API docs

- Use `only` directive for conditional reST instead
- Drops 1.6 from our text matrix, it was deprecated in 1.0 release.
  There were issues with the conditional directive only on 1.6 for some
  reason.

Co-authored-by: Benjamin Bach <benjamin@overtag.dk>
Co-authored-by: Anthony Johnson <aj@ohess.org>

.circleci/config.yml

@@ -11,7 +11,7 @@ commands:
         type: string
       sphinx-version:
         type: string
-        default: "16,17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
+        default: "17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
     steps:
       - checkout
       - run: pip install --user tox
@@ -46,7 +46,7 @@ jobs:
     steps:
       - run-tox:
           version: py27
-          sphinx-version: "16,17,18"
+          sphinx-version: "17,18"
   py36:
     docker:
       - image: 'cimg/python:3.6'

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',
@@ -41,6 +42,11 @@
 suppress_warnings = ['image.nonlocal_uri']
 pygments_style = 'default'
 
+if sys.version_info < (3, 0):
+    tags.add("python2")
+else:
+    tags.add("python3")
+
 intersphinx_mapping = {
     'rtd': ('https://docs.readthedocs.io/en/stable/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),

docs/demo/api.rst

@@ -7,11 +7,19 @@ API documentation and generated content
 :mod:`test_py_module`
 =====================
 
-.. automodule:: test_py_module.test
-    :members:
-    :private-members:
-    :special-members:
+.. only:: python3
 
+    .. automodule:: test_py_module.test
+        :members:
+        :private-members:
+        :special-members:
+
+.. only:: python2
+
+    .. automodule:: test_py_module.test_py27
+        :members:
+        :private-members:
+        :special-members:
 
 C++ API
 =======
@@ -137,3 +145,26 @@ 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
+----------------------
+
+.. only:: python3
+
+    .. autosummary::
+
+        test_py_module.test.add_numbers
+        test_py_module.test.subtract_numbers
+        test_py_module.test.Foo
+
+.. only:: python2
+
+    .. autosummary::
+
+        test_py_module.test_py27.add_numbers
+        test_py_module.test_py27.subtract_numbers
+        test_py_module.test_py27.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

@@ -1,8 +1,8 @@
 [tox]
 envlist =
     # Python 2.7 support was removed in Sphinx 2
-    py{27}-sphinx{16,17,18}{-html4,-html5,}{-qa,}
-    py{36,37,38,39}-sphinx{16,17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest}{-html4,-html5,}{-qa,}
+    py{27}-sphinx{17,18}{-html4,-html5,}{-qa,}
+    py{36,37,38,39}-sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest}{-html4,-html5,}{-qa,}
     # Python 3.10 working from Sphinx 4.2 and up
     py{310}-sphinx{42,43,44,45,50,51,52}{-html4,-html5,latest}{-qa,}
 
@@ -14,7 +14,6 @@ deps =
     readthedocs-sphinx-ext
     pytest
     sphinxcontrib-httpdomain
-    sphinx16: Sphinx>=1.6,<1.7
     sphinx17: Sphinx>=1.7,<1.8
     sphinx18: Sphinx>=1.8,<1.9
     sphinx20: Sphinx>=2.0,<2.1
@@ -40,11 +39,11 @@ deps =
     # All these Sphinx versions actually break since docutils 0.18, so we need to add this upper bound
     # Projects using these Sphinx versions will have to do the same
     # See: https://github.com/readthedocs/sphinx_rtd_theme/pull/1304
-    sphinx{16,17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42}: docutils<0.18
+    sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42}: docutils<0.18
     # External environments are required to add this dependency for older versions of Sphinx
     # because it didn't ship with this upper bound.
     # See: https://github.com/sphinx-doc/sphinx/issues/10291
-    sphinx{16,17,18,20,21,22,23,24,30,31,32,33,34,35,40}: Jinja2<3.1
+    sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40}: Jinja2<3.1
     sphinxlatest: Sphinx
     sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
 commands =