You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by "Chris M. Hostetter (Jira)" <ji...@apache.org> on 2020/10/06 01:09:00 UTC

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

     [ https://issues.apache.org/jira/browse/SOLR-14870?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Chris M. Hostetter updated SOLR-14870:
--------------------------------------
    Attachment: SOLR-14870.patch
      Assignee: Chris M. Hostetter
        Status: Open  (was: Open)

... this has taken a little longer to get into a usable shape then i expected it would, but I've got a patch attached that i think is getting pretty close to what we want for the end game.
{panel:title=digression...}
The main thing that bogged me down is that the lifecycle of gradle "tasks" really doesn't seem to make much sense, and there isn't a "clean" guide to how to refactor a "task" (instance) into a re-usable "class" that many tasks can be instances of.

I tried to start by refactoring 'prepareSources' into a "class PrepareSources extends Sync" using a doFirst closure registered in the constructor to "set up" the ivy properties that we can't read on construction/configuration – but that didn't work because gradle 'doFirst' is a lie...
 * [https://issues.gradle.org/browse/GRADLE-2064]
 * [https://discuss.gradle.org/t/dofirst-does-not-execute-first-but-only-after-task-execution/28129/6]
 * [https://github.com/gradle/gradle/issues/9142]

...the for 'TaskAction' of a gradle Task (class) is itself registered in a doFirst, which causes any 'doFirst' logic you want to register in the class to actually be done after the task is complete (there's no 'do ancestors first/last type evaluation order for doFirst/doLast like Before/After methods in junit)

So then i tried to write a new Task (class) that used composition around a private inner 'Sync' Task – but that kept getting me into weird Injection type errors (because Sync really expects gradle to Inject things). In trying to figure out if there was a hook i could call to tell the Project to "init" my Sync task (and handle all the injection) i realized that the 'Project.sync' seemed like a much more direct
 approach.

From there things got much easier, allthough I still got hung up on how some groovy syntax interacts with gradle "special sauce" ... notably: when using the "task" keyword in gradle, that's evidently just calling the task() method on the Project passing in a closure; which in groovy gets an implicit 'it' param – so when you do dynamic task declarations inside (or around) 'each' loops (where there is another implicit 'it' param) one overrides the other.
{panel}
In any case – i think I've got something nice and clean here, and would appreciate review from [~dweiss] & [~uschindler] on wether I've gone off and done anything completley insane?

Assuming i haven't, there are really just 2 outstanding nocommit's that need attention:
 * is there really no better way to get the 'main' classpath from the Project then the '...getPlugin(JavaPluginConvention.class)...' hoops i jumped through?
 * At the moment, link checking "fails" largely because it looks like the solr javadocs seem to have been restructured
 ** i need someone to sanity check for me that this is an "expected" change?
 specifically that paths like ".../solr-solrj/..." & ".../solr-ltr/..." are now going to be ".../solrj/..." & ".../ltr/..." starting in 9.0 ?
 ** examples:
 *** [https://lucene.apache.org/solr/8_6_0/solr-solrj/org/apache/solr/client/solrj/SolrClient.html]
 **** [https://lucene.apache.org/solr/9_0_0/solrj/org/apache/solr/client/solrj/SolrClient.html]
 *** [https://lucene.apache.org/solr/8_6_0/solr-core/org/apache/solr/search/XmlQParserPlugin.html]
 **** [https://lucene.apache.org/solr/9_0_0/core/org/apache/solr/search/XmlQParserPlugin.html]
** if this is all expected, then i'll move forward with updating all of the affected \*.adoc files and replace the hardcoded relative paths in the build.gradle with "clean" project(...)" based paths per Uwe's suggestion 

> 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
>            Assignee: Chris M. Hostetter
>            Priority: Major
>         Attachments: SOLR-14870.patch
>
>
> 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