[CASSANDRA-16206] Eliminate gen-doc template warning and unused (problematic) import

• Type: Bug
• Status: Resolved
• Priority: Normal
• Resolution: Fixed
• Fix Version/s: 3.11.11, 4.0-rc1, 4.0
• Component/s: Build, Documentation/Website
• Bug Category: Documentation
• Severity: Low
• Complexity: Low Hanging Fruit
• Discovered By: User Report
• Platform: All
• Since Version: 3.8

Source Control Link

https://github.com/apache/cassandra/commit/6edd7db751bb571887c84cb2f92e8226e8dd7017

Test and Documentation Plan

https://github.com/apache/cassandra/pull/771

• Assignee: Angelo Polo
• Reporter: Angelo Polo

Authors

Angelo Polo

Reviewers

Ekaterina Dimitrova, Michael Semb Wever

• Created: 10/Oct/20 11:54
• Updated: 16/Mar/22 14:22
• Resolved: 07/Apr/21 16:04

Description

1)

When running 'sphinx-build -b html -d build/doctrees source build/html'
on Linux we get the following warning:

     [exec] generating indices... genindex
     [exec] WARNING: Now base template defindex.html is deprecated.
     [exec] writing additional pages... index search

On FreeBSD this causes gen-doc to fail:

     [exec] writing additional pages...  indexfailed
     [exec]
     [exec] Theme error:
     [exec] An error happened in rendering the page index.
     [exec] Reason: UndefinedError("'warn' is undefined")
     [exec] *** Error code 2

2)

The patch to doc/source/_util/cql.py removes the unused iteritems import, preventing errors on versions of pygments 2.6.0+:

     [exec] Running Sphinx v3.2.1
     [exec]
     [exec] Exception occurred:
     [exec]   File "/path/to/apache-cassandra-4.0-beta2-src/doc/source/_util/cql.py", line 29, in <module>
     [exec]     from pygments.util import iteritems
     [exec] ImportError: cannot import name 'iteritems' from 'pygments.util' (/usr/local/lib/python3.7/site-packages/pygments/util.py)

The patch has been tested in the following environments:

• FreeBSD 12.1-RELEASE-p7
  Python 3.7.9
  Sphinx 3.2.1
  pygments 2.7.1
• Ubuntu 18.04.1
  Python 3.7.5
  Sphinx 1.6.7
  pygments 2.2.0
• Ubuntu 18.04.1
  Python 2.7.17
  Sphinx 1.6.7
  pygments 2.5.2

Issue Links

• links to: GitHub PR #771