[
https://issues.apache.org/jira/browse/SOLR-14870?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17197224#comment-17197224
]
Uwe Schindler commented on SOLR-14870:
--------------------------------------
{quote}
bq. ... Maybe we have some communication problem here (terms and semantic). ...
Almost certainly, because very little of what you said makes sense to me – and
most of that is just my lack of comprehension, only a little bit is a
disagreement about what i _do_ understand, but i suspect you are right that
it's just a terminology confusion.
{quote}
OK, sorry for being inprecise. The answer was meant for [~dweiss]. I have read
you text and maybe for clarification on your side I will (again) explain what's
completely different in Gradle with regards to Javadocs:
The gradle build actually builds 2 different versions of the Javadocs:
- One called "local javadocs" which are per project: Every Lucene / Solr module
has its own "small" piece of Javadocs residing in the projects subfolder. Those
Javadocs are isolated and intended to be packaged into Javadoc-JAR files
available to IDEs and other consumers from Maven central. Those Javadocs never
go to any website and therefor they are also not the "target for link checks".
- The other "global javadocs" variant is part of "gradlew :documentation" or
"gradlew :lucene:documentation" (if you only want Lucene. This task builds the
Javadocs as they are published on the website. Those javadocs are then located
at {{$\{project(':lucene').buildDir\}/documentation}} and are copied to web
page. They have exactly the structure like published on the website. The final
location may change, as I am planning to make the global javadocs a separate
subproject of lucene/solr (to assemble those). But with above logic it wold
just be a change in the above {{project()}} path, so you don't need to take
care.
As you see from that, IMHO the ideal way to check the links would be the
following:
- The checklinks task in the refguide depends on the "global javadocs" /
"documentation" task (as its Lucene only, right?). Ideally it should rely on
its output (I can fix this to declare the documentation folder as its output),
then the dependency would be on the output folder.
- When checklinks is running, it just passes above project output, converted to
URI, to the checker task or the build refguide task. This should be done
always, as the output to be checked never depends on external resources.
- Ideally for checking purposes the gradle build should have 2 different tasks
(one that builds the real refguide with absolute links, and one just for
checking purposes to another output folder, using the above project-URL).
Does this now sound doable? If I have some time tomorrow morning, I may be able
to help you.
> 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-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
