[CASSANDRA-17684] MacOS install should include cql.html local help file

• Type: Improvement
• Status: Open
• Priority: Normal
• Resolution: Unresolved
• Fix Version/s: 5.x
• Component/s: CQL/Interpreter
• Change Category: Operability
• Complexity: Low Hanging Fruit
• Platform: All

Test and Documentation Plan

I ensured the given patch was activated in the if statement through print statements. If the cql.html file was to open in the given browser, the patch ran properly.

• Assignee: Unassigned
• Reporter: Brad Schoening
• Created: 07/Jun/22 01:06
• Updated: 19/Dec/23 03:22

Description

On MacOS, /usr/share is not writable – even by root. Instead, /usr/local/share is the preferred location.

The current share directory path is /usr/share/doc/cassandra/CQL.html.  This would just add an alternative path.

Using a list comprehension would simplify the current code.  E.g.,     

import pathlib

HTML_FALLBACK = 'https://cassandra.apache.org/doc/latest/cql/index.html'

loc = [ f"{pkgpath}/doc/cql3/CQL.html', "/usr/share/doc/cassandra/CQL.html", "/usr/local/share/doc/cassandra/CQL.html" ]

item = next((x.as_uri() for x in loc if Path( x ).exists()), HTML_FALLBACK)

Homebrew doesn't install the doc files, so this would likely need either

a) added to homebrew in https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/cassandra.rb

or

b) installed with pip's setup.cql and accessed with Python's importlib.resources

Issue Links

• links to: https://github.com/apache/cassandra/pull/2592