mirror of https://github.com/apache/cassandra
Autogenerate Native protocol specifications documentation
Uses cqlprotodoc from cassandra-website to generate the versioned native protocol spec html pages. Uses process-native-protocol-specs-in-docker.sh as a wrapper around this to also generate the native protocol spec adoc page that includes all the versions and makes each header navigable. This is executed as part of the existing `ant gen-asciidoc` and doc/Makefile. patch by Olexandr Luzhniy; reviewed by Mick Semb Wever for CASSANDRA-19915
This commit is contained in:
tengu-alt
Mick Semb Wever
parent
f59a90b895
commit
17de6a67a2
|
|
@ -13,6 +13,7 @@
|
|||
|
||||
GENERATE_NODETOOL_DOCS = ./scripts/gen-nodetool-docs.py
|
||||
MAKE_CASSANDRA_YAML = ./scripts/convert_yaml_to_adoc.py ../conf/cassandra.yaml ./modules/cassandra/pages/managing/configuration/cass_yaml_file.adoc
|
||||
PROCESS_NATIVE_PROC_SPECS = ./scripts/process-native-protocol-specs-in-docker.sh
|
||||
|
||||
.PHONY: html
|
||||
html:
|
||||
|
|
@ -24,3 +25,4 @@ gen-asciidoc:
|
|||
@mkdir -p modules/cassandra/examples/TEXT/NODETOOL
|
||||
python3 $(GENERATE_NODETOOL_DOCS)
|
||||
python3 $(MAKE_CASSANDRA_YAML)
|
||||
$(PROCESS_NATIVE_PROC_SPECS)
|
||||
|
|
|
|||
|
|
@ -40,7 +40,8 @@ If you would like to contribute to this documentation, you are welcome to do so
|
|||
|
||||
| xref:cassandra:integrating/plugins/index.adoc[Plug-ins] | Third-party plug-ins
|
||||
|
||||
| xref:master@_:ROOT:native_protocol.adoc[Native Protocols] | Native Cassandra protocol specifications
|
||||
| link:cassandra/reference/native-protocol.html[Native Protocols] | Native Cassandra protocol specifications
|
||||
|
||||
|===
|
||||
|
||||
== Meta information
|
||||
|
|
|
|||
|
|
@ -728,7 +728,7 @@ Table of Contents
|
|||
Clients are expected to answer the server challenge by an AUTH_RESPONSE
|
||||
message.
|
||||
|
||||
4.2.7. AUTH_SUCCESS
|
||||
4.2.8. AUTH_SUCCESS
|
||||
|
||||
Indicate the success of the authentication phase. See Section 4.2.3 for more
|
||||
details.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,6 @@ Table of Contents
|
|||
2.3.1 Initial Handshake
|
||||
2.3.2 Compression
|
||||
2.4. Frame Payload
|
||||
2.4.1 Frame Header
|
||||
2.4.1.1. version
|
||||
2.4.1.2. flags
|
||||
2.4.1.3. stream
|
||||
|
|
@ -232,7 +231,7 @@ Table of Contents
|
|||
All values in an envelope are big-endian (network byte order).
|
||||
|
||||
Each envelope contains a fixed size header (9 bytes) followed by a variable size
|
||||
body. The header is described in Section 2.4.1. The content of the body depends
|
||||
body. The content of the body depends
|
||||
on the header opcode value (the body can in particular be empty for some
|
||||
opcode values). The list of allowed opcodes is defined in Section 2.4.1.4 and the
|
||||
details of each corresponding message are described Section 4.
|
||||
|
|
@ -255,7 +254,7 @@ Table of Contents
|
|||
previously possible to enable compression for an individual envelope. This is no
|
||||
longer possible, as the framing format is responsible for compression, which is set for
|
||||
the lifetime of a connection and applies to all messages transmitted throughout it
|
||||
(see Section 2.2.1 for caveats). The compression flag is therefore deprecated and
|
||||
(see Section 2.2 for caveats). The compression flag is therefore deprecated and
|
||||
ignored in protocol v5.
|
||||
|
||||
2.4.1.1. version
|
||||
|
|
@ -277,7 +276,7 @@ Table of Contents
|
|||
connection.
|
||||
|
||||
This document describes version 5 of the protocol. For the changes made since
|
||||
version 4, see Section 10.
|
||||
version 4, see Section 9.
|
||||
|
||||
2.4.1.2. flags
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,126 @@
|
|||
#!/bin/sh
|
||||
# Licensed to the Apache Software Foundation (ASF) under one
|
||||
# or more contributor license agreements. See the NOTICE file
|
||||
# distributed with this work for additional information
|
||||
# regarding copyright ownership. The ASF licenses this file
|
||||
# to you under the Apache License, Version 2.0 (the
|
||||
# "License"); you may not use this file except in compliance
|
||||
# with the License. You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
[ -f "../build.xml" ] || { echo "build.xml must exist (current directory needs to be doc/ in cassandra repo"; exit 1; }
|
||||
[ -f "antora.yml" ] || { echo "antora.yml must exist (current directory needs to be doc/ in cassandra repo"; exit 1; }
|
||||
|
||||
# Variables
|
||||
GO_VERSION="1.23.1"
|
||||
GO_TAR="go${GO_VERSION}.linux-amd64.tar.gz"
|
||||
TMPDIR="${TMPDIR:-/tmp}"
|
||||
|
||||
# Step 0: Download and install Go
|
||||
echo "Downloading Go $GO_VERSION..."
|
||||
wget -q "https://golang.org/dl/$GO_TAR" -O "$TMPDIR/$GO_TAR"
|
||||
|
||||
echo "Installing Go..."
|
||||
tar -C "$TMPDIR" -xzf "$TMPDIR/$GO_TAR"
|
||||
rm "$TMPDIR/$GO_TAR"
|
||||
|
||||
# Set Go environment variables
|
||||
export PATH="$PATH:$TMPDIR/go/bin"
|
||||
export GOPATH="$TMPDIR/go"
|
||||
|
||||
# Step 1: Building the parser
|
||||
echo "Building the cqlprotodoc..."
|
||||
DIR="$(pwd)"
|
||||
cd "${TMPDIR}"
|
||||
|
||||
git clone -n --depth=1 --filter=tree:0 https://github.com/apache/cassandra-website
|
||||
|
||||
cd "${TMPDIR}/cassandra-website"
|
||||
git sparse-checkout set --no-cone /cqlprotodoc
|
||||
git checkout
|
||||
cd "${TMPDIR}/cassandra-website/cqlprotodoc"
|
||||
go build -o "$TMPDIR"/cqlprotodoc
|
||||
|
||||
# Step 2: Process the spec files using the parser
|
||||
echo "Processing the .spec files..."
|
||||
cd "${DIR}"
|
||||
output_dir="modules/cassandra/attachments"
|
||||
mkdir -p "${output_dir}"
|
||||
"$TMPDIR"/cqlprotodoc . "${output_dir}"
|
||||
|
||||
# Step 4: Generate summary file
|
||||
summary_file="modules/cassandra/pages/reference/native-protocol.adoc"
|
||||
|
||||
# Write the header
|
||||
echo "= Native Protocol Versions" > "$summary_file"
|
||||
echo ":page-layout: default" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
|
||||
# Loop through the files from step 2 in reverse version order
|
||||
for file in $(ls ${output_dir}/native_protocol_v*.html | sort -r | awk -F/ '{print $NF}'); do
|
||||
version=$(echo "$file" | sed -E 's/native_protocol_v([0-9]+)\.html/\1/')
|
||||
echo "== Native Protocol Version $version" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo "[source, html]" >> "$summary_file"
|
||||
echo "++++" >> "$summary_file"
|
||||
echo "include::cassandra:attachment\$$file[Version $version]" >> "$summary_file"
|
||||
echo "++++" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
done
|
||||
|
||||
# Navigation setup
|
||||
echo "[source, js]" >> "$summary_file"
|
||||
echo "++++" >> "$summary_file"
|
||||
echo "<script>" >> "$summary_file"
|
||||
echo " function setNavigation() {" >> "$summary_file"
|
||||
echo " var containers = document.querySelectorAll('.sect1');" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " containers.forEach(function (container) {" >> "$summary_file"
|
||||
echo " var preElements = container.querySelectorAll('pre');" >> "$summary_file"
|
||||
echo " preElements.forEach(function(preElement) {" >> "$summary_file"
|
||||
echo " if (!preElement.textContent.trim()) {" >> "$summary_file"
|
||||
echo " preElement.remove();" >> "$summary_file"
|
||||
echo " }" >> "$summary_file"
|
||||
echo " });" >> "$summary_file"
|
||||
echo " var h1Elements = container.querySelectorAll('h1');" >> "$summary_file"
|
||||
echo " h1Elements.forEach(function(h1Element) {" >> "$summary_file"
|
||||
echo " h1Element.remove();" >> "$summary_file"
|
||||
echo " });" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " var navLinks = container.querySelectorAll('nav a, pre a');" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " navLinks.forEach(function (link) {" >> "$summary_file"
|
||||
echo " link.addEventListener('click', function (event) {" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " event.preventDefault();" >> "$summary_file"
|
||||
echo " var section = link.getAttribute('href').replace(\"#\", '');" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " var targetSection = container.querySelector('h2[id=\"' + section + '\"]') || container.querySelector('h3[id=\"' + section + '\"]') || container.querySelector('h4[id=\"' + section + '\"]') || container.querySelector('h5[id=\"' + section + '\"]');" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " if (targetSection) {" >> "$summary_file"
|
||||
echo " targetSection.scrollIntoView({ behavior: 'smooth' });" >> "$summary_file"
|
||||
echo " }" >> "$summary_file"
|
||||
echo " });" >> "$summary_file"
|
||||
echo " });" >> "$summary_file"
|
||||
echo " });" >> "$summary_file"
|
||||
echo " }" >> "$summary_file"
|
||||
echo >> "$summary_file"
|
||||
echo " window.onload = function() {" >> "$summary_file"
|
||||
echo " setNavigation()" >> "$summary_file"
|
||||
echo " }" >> "$summary_file"
|
||||
echo " </script>" >> "$summary_file"
|
||||
|
||||
|
||||
# Step 3: Cleanup - Remove the Cassandra and parser directories
|
||||
echo "Cleaning up..."
|
||||
cd "${DIR}"
|
||||
rm -rf "${TMPDIR}/go" "${TMPDIR}/cassandra-website" "${TMPDIR}/cqlprotodoc" 2>/dev/null
|
||||
|
||||
echo "Script completed successfully."
|
||||
Loading…
Reference in New Issue