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.

.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

@@ -42,6 +42,11 @@ master_doc = 'index'
 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
 =======
@@ -145,10 +153,18 @@ Sphinx Extensions
 sphinx.ext.autosummary
 ----------------------
 
-.. autosummary::
+.. only:: python3
 
-   test_py_module.test.add_numbers
-   test_py_module.test.subtract_numbers
-   test_py_module.test.Foo
+    .. 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

tox.ini

@@ -1,15 +1,12 @@
 [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,}
 
 [testenv]
-allowlist_externals =
-    cp
-    rm
 setev =
     LANG=C
 deps =
@@ -17,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
@@ -43,22 +39,14 @@ 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 =
     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