janhoy commented on code in PR #4271:
URL: https://github.com/apache/solr/pull/4271#discussion_r3050876135
##########
solr/solr-ref-guide/build.gradle:
##########
@@ -540,6 +545,209 @@ task buildOfficialSite(type: NpxTask) {
}
}
+/*
+ CLI Documentation Generation from Picocli Annotations
+ Generates per-command AsciiDoc reference pages for the Antora ref guide.
+ Usage:
+ ./gradlew :solr:solr-ref-guide:generateCliDocs -- regenerate pages/cli/
+ ./gradlew :solr:solr-ref-guide:checkCliDocsUpToDate -- verify in-sync (also
run by check)
+ */
+
+def ASF_LICENSE_HEADER = """\
+// 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.
+"""
+
+def DO_NOT_EDIT_NOTICE = """\
+// DO NOT EDIT -- this page is auto-generated from picocli annotations.
+// To update: modify the @Command/@Option annotations in the Java source, then
run:
+// ./gradlew :solr:solr-ref-guide:generateCliDocs
+"""
+
+// Convert a generated filename stem (e.g. "solr-zk-ls") to an Antora page
title
+// e.g. "solr-zk-ls" -> "bin/solr zk ls"
+String cliFileNameToTitle(String baseName) {
+ def parts = baseName.split('-')
+ return "bin/solr " + parts.drop(1).join(' ')
+}
+
+// Return the short nav label for a command file (last segment of
dash-separated name)
+// e.g. "solr-zk-ls" -> "ls"
+String cliFileNameToNavLabel(String baseName) {
+ return baseName.split('-').last()
+}
+
+// Post-process a raw ManPageGenerator AsciiDoc file for Antora compatibility.
+// The title lives inside the man-section-header block, so we replace the whole
+// header block with an Antora-compatible page title + attributes.
+String postProcessCliManPage(File rawFile, String asfHeader, String
doNotEditNotice) {
+ def content = rawFile.text
+ def baseName = rawFile.name.replace('.adoc', '')
+ def newTitle = cliFileNameToTitle(baseName)
+
+ // Replace the entire man-section-header block (which contains
:doctype:manpage, the page title
+ // "= solr-start(1)", etc.) with our Antora-compatible title and page
attributes.
+ content = content.replaceAll(
+ /(?s)\/\/ tag::picocli-generated-man-section-header\[\].*?\/\/
end::picocli-generated-man-section-header\[\]\n\n?/,
+ "= ${newTitle}\n:page-toclevels: 2\n\n")
+
+ // ManPageGenerator renders the command's qualified name as "bin/solr-start"
(parent-dash-child).
+ // Replace occurrences of that with the correct spaced form "bin/solr start".
+ def picocliQualifiedName = 'bin/solr-' + baseName.substring('solr-'.length())
+ content = content.replace(picocliQualifiedName, newTitle)
+
+ // Strip the outer full-manpage tag wrappers
+ content = content.replace("// tag::picocli-generated-full-manpage[]\n", '')
+ content = content.replace("// end::picocli-generated-full-manpage[]\n", '')
+
+ return asfHeader + doNotEditNotice + "\n" + content.stripTrailing() + "\n"
+}
+
+// Build the CLI sub-page nav entries from the generated .adoc files in
destDir.
+// Returns a list of nav lines like "** xref:cli/solr-start.adoc[start]"
+List<String> buildCliNavEntries(File cliDir) {
+ // Sort so that parent commands always precede their children.
+ // The trick: append '\u0000' (NUL, ASCII 0) to the stem before sorting.
+ // NUL < '-' (ASCII 45), so "solr-zk\0" < "solr-zk-cp\0", placing the parent
first.
+ def files = ((cliDir.listFiles() ?: []) as List<File>)
+ .findAll { it.name.endsWith('.adoc') }
+ .sort { (it.name.replace('.adoc', '') + '\u0000') }
+ return files.collect { file ->
+ def baseName = file.name.replace('.adoc', '')
+ def parts = baseName.split('-')
+ // depth: "solr-start" has 2 parts → "**", "solr-zk-ls" has 3 parts → "***"
+ def stars = '*' * parts.length
+ def label = cliFileNameToNavLabel(baseName)
+ "${stars} xref:cli/${file.name}[${label}]"
+ }
+}
+
+// Run ManPageGenerator and return the set of generated files (excluding the
top-level solr.adoc).
+// Because SolrCLI is annotated @Command(name="bin/solr"), ManPageGenerator
writes all files into
+// a "bin/" subdirectory of outputDir (e.g. outputDir/bin/solr-start.adoc).
Review Comment:
Fix this - use `name="solr"` and remove this hack
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
