diff options
author | Anthony Johnson <aj@ohess.org> | 2022-11-04 21:16:57 +0300 |
---|---|---|
committer | Anthony Johnson <aj@ohess.org> | 2022-11-04 21:45:45 +0300 |
commit | 440984d85033019a6cf3e68a11af45bc5ade9d9c (patch) | |
tree | aef6b9f381bba3b3b36fd9f9693dd54df53f5ad1 | |
parent | 3e6488ef0a80f86264bc53224c2190104349ac7d (diff) |
Use a less hacky way of conditional autosummary in demo API docsagj/pr-1369
- 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.
-rw-r--r-- | .circleci/config.yml | 4 | ||||
-rw-r--r-- | docs/conf.py | 5 | ||||
-rw-r--r-- | docs/demo/api.rst | 32 | ||||
-rw-r--r-- | tox.ini | 20 |
4 files changed, 35 insertions, 26 deletions
diff --git a/.circleci/config.yml b/.circleci/config.yml index ac8a665..690191f 100644 --- a/.circleci/config.yml +++ b/.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' diff --git a/docs/conf.py b/docs/conf.py index 665aad0..2973027 100644 --- a/docs/conf.py +++ b/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), diff --git a/docs/demo/api.rst b/docs/demo/api.rst index 111d357..ae23df7 100644 --- a/docs/demo/api.rst +++ b/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 + + .. autosummary:: + + test_py_module.test.add_numbers + test_py_module.test.subtract_numbers + test_py_module.test.Foo - 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 @@ -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 |