[jira] [Comment Edited] (SOLR-14870) gradle build does not validate ref-guide -> javadoc links

["Uwe Schindler (Jira)" <ji...@apache.org>]

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

Uwe Schindler edited comment on SOLR-14870 at 9/16/20, 8:05 AM:
----------------------------------------------------------------

Actually the links refguide -> javadocs should setup a link to the "global" javadocs. The local "javadocs" (as packaged into Maven Javadocs-JAR files) are not in the deal. Maybe we have some communication problem here (terms and semantic).

About [~dweiss]'s comments:

bq. this should not be the case. If docs are to be rendered with local links they should be rendered separately (different task, different outputs). This ensures caches (up-to-date) are working correctly. That global "local.javadocs" should be removed, in other words.

I agree! The problem here is manifold:

- The global javadocs (which should be a separate subproject for packaging) should have this externally configureable link (so Jenkins or release manager can adapt the links) -> see below, here the links are fine
- The local Javadocs (which are packaged into Maven javadocs-JARS and that are local to project folders) should not have any outside links, because they are always viewed in isolation (e.g., inside IDE). I'd just disable all inter-project links for them. Then there's also no need to check links. There should not even be a link between Lucene subprojects.

bq. Our "global" javadocs are rendered conditionally too (see documentation.gradle)

That's fine, as its a constant for the whole build. When it changes, the inputs of renderJavadocs changes and all files are regenerated. You can easily test this by passing another javadoc URL with {{-P}} and the documentation is regenerated. I tested this several times when I implemented this.


was (Author: thetaphi):
Actually the links refguide -> javadocs should setup a link to the "global" javadocs. The local "javadocs" (as packaged into Maven Javadocs-JAR files) are not in the deal. Maybe we have some communication problem here (terms and semantic).

About [~dweiss]'s comments:

bq. this should not be the case. If docs are to be rendered with local links they should be rendered separately (different task, different outputs). This ensures caches (up-to-date) are working correctly. That global "local.javadocs" should be removed, in other words.

I agree! The problem here is manifold:

- The global javadocs (which should be a separate subproject for packaging) should have this externally configureable link (so Jenkins or release manager can adapt the links) -> see below, here the links are fine
- The local Javadocs (which are packaged into Maven javadocs-JARS and that are local to project folders) whoulc not have any outside links, because they are always viewed in isolation (e.g., inside IDE). I'd just disable all inter-project links for them. Then there's also no need to check links. There should not even be a link between Lucene subprojects.

bq. Our "global" javadocs are rendered conditionally too (see documentation.gradle)

That's fine, as its a constant for the whole build. When it changes, the inputs of renderJavadocs changes and all files are regenerated. You can easily test this by passing another javadoc URL with {{-P}} and the documentation is regenerated. I tested this several times when I implemented this.

> gradle build does not validate ref-guide -> javadoc links
> ---------------------------------------------------------
>
>                 Key: SOLR-14870
>                 URL: https://issues.apache.org/jira/browse/SOLR-14870
>             Project: Solr
>          Issue Type: Task
>      Security Level: Public(Default Security Level. Issues are Public) 
>            Reporter: Chris M. Hostetter
>            Priority: Major
>
> the ant build had (has on 8x) a feature that ensured we didn't have any broken links between the ref guide and the javadocs...
> {code}
>   <target name="documentation" description="Generate all documentation"
>           depends="javadocs,changes-to-html,process-webpages">
>     <ant dir="solr-ref-guide" target="bare-bones-html-validation" inheritall="false">
>       <propertyset refid="uptodate.and.compiled.properties"/>
>       <property name="local.javadocs" value="true" />
>     </ant>
>   </target>
> {code}
> ...by default {{cd solr/solr-ref-guide && ant bare-bones-html-validation}} just did interanal validation of the strucure of the guide, but this hook ment that {{cd solr && ant documentation}} (or {{ant precommit}}) would first build the javadocs; then build the ref-guide; then validate _all_ links i nthe ref-guide, even those to (local) javadocs
> While the "local.javadocs" property logic _inside_ the solr-ref-guide/build.xml was ported to build.gradle, the logic to leverage this functionality from the "solr" project doesn't seem to have been preserved -- so currently, {{gradle check}} doesn't know/care if someone adds a nonsense javadoc link to the ref-guide (or removes a class/method whose javadoc is already currently to from the ref guide)



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

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org