[
https://issues.apache.org/jira/browse/SOLR-14870?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17196735#comment-17196735
]
Dawid Weiss commented on SOLR-14870:
------------------------------------
[~uschindler] and [~tomoko] have more knowledge about how the documentation is
assembled. They should probably chip in on how to solve it...
My superficial look at the ported gradle suggests that it is all wrong at the
moment because rendering is conditional on a top-level property:
{code}
if (project.hasProperty("local.javadocs")) {
htmlSolrJavadocs = "link:../../docs/"
htmlLuceneJavadocs = "link:../../../../lucene/build/docs/"
} else {
htmlSolrJavadocs =
"https://lucene.apache.org/solr/${solrDocsVersionPath}/";
htmlLuceneJavadocs =
"https://lucene.apache.org/core/${solrDocsVersionPath}/";
}
{code}
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.
Our "global" javadocs are rendered conditionally too (see documentation.gradle):
{code}
luceneDocUrl = project.propertyOrDefault('lucene.javadoc.url', {
if (project.version != project.baseVersion) {
// non-release build
project('lucene').file('build/documentation').toURI().toASCIIString()
} else {
// release build
"https://lucene.apache.org/core/${urlVersion}";
}
}())
solrDocUrl = project.propertyOrDefault('solr.javadoc.url', {
if (project.version != project.baseVersion) {
// non-release build
project('solr').file('build/documentation').toURI().toASCIIString()
} else {
// release build
"https://lucene.apache.org/solr/${urlVersion}";
}
}())
{code}
I'm not sure if this will affect guide link validation anyhow.
bq. add a distinct task, similar to buildSite, that sets up the localJavadocs
property in a doFirst block
It should be two different tasks - one rendering links to local javadocs, the
other to remote ones. 'buildSite' should be in fact called
'checkSite(Local|Remote)' because that's what it does.
> change check.dependsOn buildSite to depend on this new task instead of
> buildSite
Yes, seems like it.
> add documentation.dependsOn that depends on this new task
I wouldn't mix generation and validation tasks. When you say "gradlew
documentation" you generate. When you say "gradlew check", you validate (and
generate, if needed). That solr-ref-guide validation *depends* on the generated
javadocs from all projects is quite unfortunate because it'll cause everything
to recompute but if this is how it works then so be it. The way it should be
modeled (I think) is that "checkSiteLocal" task should depend on
":documentation" (root project's documentation task). Then you know its outputs
are up-to-date. I'm not sure about the local vs. remote links in that generated
documentation though.
> 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: [email protected]
For additional commands, e-mail: [email protected]
