Skip to content

SOLR-18469: Use the tabs format for v1/v2 API examples in two pages - #4928

Open
serhiy-bzhezytskyy wants to merge 1 commit into
apache:mainfrom
serhiy-bzhezytskyy:SOLR-18469-v1v2-tabs
Open

serhiy-bzhezytskyy wants to merge 1 commit into
apache:mainfrom
serhiy-bzhezytskyy:SOLR-18469-v1v2-tabs

Conversation

@serhiy-bzhezytskyy

Copy link
Copy Markdown
Contributor

https://issues.apache.org/jira/browse/SOLR-18469

Description

implicit-requesthandlers.adoc listed v1/v2 endpoint pairs as plain text inside table cells instead of the [tabs] V1/V2 format used elsewhere in the guide. Grepped for the same pattern across the rest of the guide and found one other page with it: basic-authentication-plugin.adoc, which already uses [tabs] for its other examples on the same page, just not for its "API Entry Point" section.

Solution

implicit-requesthandlers.adoc uses compact 3-column reference tables (API Endpoint(s) | Class & Javadocs | Paramset) rather than full runnable examples, so the v1/v2 split lives inside a table cell. AsciiDoc table cells only support block content like [tabs] when marked a| instead of |. Converted every row that has both a v1 and v2 form this way: Health, Logging, Properties, Threads, Config, and Schema (which has two v1 paths and two v2 paths -- both lines go inside their respective tab). Left "Core Info" alone -- it only has a v1 endpoint, nothing documented for v2, so there's nothing to pair it with.

basic-authentication-plugin.adoc's "API Entry Point" section (two bare URLs) converted to the same [tabs] style already used elsewhere on that same page.

Tested the table-cell approach before applying it everywhere: converted one row, built the actual HTML (not just checked for a clean Asciidoctor pass), and confirmed the tabs/tabpanel/tablist structure renders the same way nested in a <td> as it does at the top level.

Tests

Ran ./gradlew :solr:solr-ref-guide:buildLocalAntoraSite and :checkSiteLinks: same 6 pre-existing warnings (unrelated, tracked in #4922/SOLR-18464), no new ones, no broken links. Also ran buildLocalSite and inspected the generated HTML directly for the tabs DOM structure.

AI-assisted (Claude Sonnet 5).

implicit-requesthandlers.adoc and basic-authentication-plugin.adoc listed v1 and v2 endpoints as plain text instead of the [tabs] V1/V2 API format used elsewhere in the guide. Converted every row that has both a v1 and v2 form; left the one row that only has v1 (Core Info) untouched, since there's nothing to pair it with.
@serhiy-bzhezytskyy

Copy link
Copy Markdown
Contributor Author

@epugh tagging you since this is under SOLR-18459/SOLR-18469, which you filed.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 20, 2026
@epugh

epugh commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

I am surprised this pattern was more common across our code base? Maybe we need to also audit in another pr "places we show v1 but not v2" and have a v2..

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants