[CASSANDRA-17534] CQLSH help topic links are broken between textile and online files

• Type: Bug
• Status: Resolved
• Priority: Normal
• Resolution: Fixed
• Fix Version/s: 3.0.30, 3.11.16, 4.0.12, 4.1.4, 5.0-alpha1, 5.0
• Component/s: CQL/Interpreter
• Bug Category: Documentation
• Severity: Normal
• Complexity: Low Hanging Fruit
• Discovered By: User Report
• Platform: All
• Since Version: NA

Source Control Link

https://github.com/apache/cassandra/commit/28c04fbdde56c4a4e20aadd38952b5148467e443

Test and Documentation Plan

We found the correct link to be  https://cassandra.apache.org/doc/latest/cassandra/cql/cql_singlefile.html and tested all of the help functions with the new link.

• Assignee: Vineet Gali
• Reporter: Brad Schoening

Authors

Vineet Gali

Reviewers

Stefan Miklosovic

• Created: 07/Apr/22 00:32
• Updated: 12/Sep/23 13:02
• Resolved: 08/Aug/23 16:25

Description

CQLSH help topics opens a generic CQL page, not the specific topic.  This happens when docs are not installed locally, and it tries to open the online version.

The file cqlsh.py has:

    # default location of local CQL.html
    if os.path.exists(CASSANDRA_PATH + '/doc/cql3/CQL.html'):
     ....
    else:
    # fallback to online version
    CASSANDRA_CQL_HTML = CASSANDRA_CQL_HTML_FALLBACK

For example,

cqlsh> help truncate;

opens the page:

https://cassandra.apache.org/doc/latest/cassandra/cql/index.html#truncateStmt

but there is no information about 'truncate' on that page and the anchor #truncateStmt doesn't exist.

the correct page anchor is:

https://cassandra.apache.org/doc/latest/cassandra/cql/ddl.html#truncate-statement

The local file anchors appear they may be incorrect as well:

https://github.com/apache/cassandra/blob/trunk/doc/cql3/CQL.textile#truncate

To reproduce this, 'pip install cqlsh' on a machine without a Cassandra package install.

Issue Links

• fixes: CASSANDRA-16336 cqlsh help command displays a broken url
• is related to: CASSANDRA-16336 cqlsh help command displays a broken url
• links to: https://github.com/apache/cassandra/pull/2512
• links to: https://github.com/apache/cassandra/pull/2514
• links to: https://github.com/apache/cassandra/pull/2528
• links to: https://github.com/apache/cassandra/pull/2529
• links to: https://github.com/apache/cassandra/pull/2530