[jira] [Commented] (SOLR-15262) deal with "local" ref-guide link checking after lucene/solr repo split

["Chris M. Hostetter (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-15262?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17301812#comment-17301812 ] 

Chris M. Hostetter commented on SOLR-15262:
-------------------------------------------



Some context of this issue...

The ref-guide build system has always assumed the lucene version and the solr version are the same, and generated a {{htmlLuceneJavadocs}} "url prefix" for use as a variable in ref-guide files when documentation wishes to link to lucene javadocs.  For "official" ref-guide builds the build system would generate a link using logic like...

{code}
"https://lucene.apache.org/core/${solrGuideVersionPath}_0/"
{code}

...but there is also a "local" site build used for link checking that would generate a path using logic like...

{code}
'link:../' + buildDir.toPath().relativize(project(':lucene:documentation').docroot.toPath()).toString().replace(File.separator, '/')
{code}

...this has been incredibly helpful since the it helps us catch documentation that refers to lucene classes/features which might be moved/renamed/deleted.


As part of the lucene/solr git repo split, Dawid needed to add this special hook to disable checkLocalJavadocLinksSite because the lucene javadocs are no longer locally buildable...
{code:java}
hossman@slate:~/lucene/solr [main] $ tail -6 gradle/solr-tlp-migration/disable-links-checking.gradle
configure(project(":solr:solr-ref-guide")) {
  tasks.matching { it.name == "checkLocalJavadocLinksSite" }.all {
    enabled = false
    logger.warn("Skipping checkLocalJavadocLinksSite (tlp git migration)")
  }
}
{code}
 
----

This Jira exists to tackle dealing with this situation, via a few iterative improvements I can think of (that i'll open as sub tasks):

* treat lucene javadocs as "remote" even in the "Local" site so that the link checking logic ignores them and we can get back to at least validating solr javadoc links
* refactoring the URL prefix logic to pull the lucene version from ivy properties (like we do for other 3rd party dependencies)
* come up with a longer term plan for if/how we want to "validate" links to lucene javadocs
** we currently don't do any validation of links to "remote" urls in the ref-guide content -- regardless of wether they are hardcoded or version specific via ivy properties
** we may want to revisit that now ... either in general, or via some lucene specific logic (possibly via fetching lucene src or javadoc jars) since we have so many links to lucene class javadocs


> deal with "local" ref-guide link checking after lucene/solr repo split
> ----------------------------------------------------------------------
>
>                 Key: SOLR-15262
>                 URL: https://issues.apache.org/jira/browse/SOLR-15262
>             Project: Solr
>          Issue Type: Task
>      Security Level: Public(Default Security Level. Issues are Public) 
>            Reporter: Chris M. Hostetter
>            Assignee: Chris M. Hostetter
>            Priority: Major
>
> The main goal of this issue (and some sub-tasks i expect to create) is to "fix" the way the ref-guide deals with links to lucene javadocs in the post-TLP split world where lucene src/javadoc links are not readily part of the solr repo 



--
This message was sent by Atlassian Jira
(v8.3.4#803005)