[ https://issues.apache.org/jira/browse/SOLR-14870?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17197151#comment-17197151 ]
Chris M. Hostetter commented on SOLR-14870: ------------------------------------------- {quote}... Maybe we have some communication problem here (terms and semantic). ... {quote} 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. So here's some more detailed background / specifies / defining terms solely from the point of view of the ref-guide build process – ignoring for a moment the changes being planned/discussed in SOLR-14824... the ref-guide build (both ant and gradle) has 2 orthogonal concepts: * how we "build" the guide into HTML, via different tasks/targets ** "buildSite" uses jekyll ** "bareBonesAsciiDoctor" uses asciidoctor directly * the prefix used in the generated HTML, via the "local.javadocs" property ** if true, use prefixes like "../../docs/" *AND THOSE LINKS WILL LATER BE VALIDATED* ** if false, use prefixes like "https://lucene.apache.org/..." (which implicitly won't be validated) The fact that those 2 concepts are orthogonal, is really just a historical oddity of how we use to build a PDF, but couldn't do link validation in the PDF; and how hard it is/was to run "jekyll" from ant; and the fact that we wanted some automated validation that could be hooked into "precommit". * The "local.javadocs" property was never really meant for a human to set when running any targets/tasks directly in the ref-guide. * Likewise no human was ever expected to *READ* the "bare bones" ref-guide output. Both of those concepts existed purely so that when "ant precommit" (conceptually) depended on "cd solr && ant documentation" that would then ensure that ref-guide was forcibly re-generated (because there was no caching of the ref-guide build outputs) so we could verify no malformed adoc files, and the generated HTML would use "../../etc..." style javadoc links which could be easily validated locally. Uwe: Does that all make sense in terms of the terminology / purpose of the "local.javadocs" param i mentioned? we really only have have one "site" output (built via jekyll) that we actually care about people viewing/publishing, and it (historically) has always used "https://..." style links for the javadocs. (whether we want to change that down the road to be more configurable if/when we tie the ref-guide into top level "package/publish" actions seems like it's a bigger question for another jira?) ---- If we were to start over today (even in ant where w/all of it's problems running jekyll directly) where we no longer care about the PDF, and we have a "check" task/target inside each sub-project (not just a top level "precommit") then (along hte lines of what Dawid said) instead of 2x2 ways to build the guide, it would probably make sense to just have 2 ways to build the guide, w/o the project level "local.javadocs" property at all... * "buildSite" would use jekyll with all javadoc links pointing to "http://lucene.apache.org/..." ** when we later run the "link checker" on this, it would ignore the remote links javadoc links (just like it ignores any external link) * "bareBonesAsciiDoctor" would use asciidoctor directly, with all javadoc links pointing to "../../etc..." ** when we later run the "link checker" on this, it would validate those links Which brings me to Dawid's comment, which i think really hits hte nail on the head in terms of my primary concern as to how to do this in the "gradle-esque" way... {quote}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, {quote} Right. I'm staring to drink the gradle Kool-Aid now in terms of intermediate outputs and caching... {quote}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. {quote} Hmmm... but if i'm following you correctly, it should really be 4 tasks: * buildSite ** just handle adoc -> html converstion via jekyll into some "build/site" directory ** use "http://..." style javadoc links * buildBareBonesHtml ** just handle adoc -> html conversion via asciidoctor into some "build/bare-bones" directory ** "../../etc..." style javadoc links * checkSite ** depend on buildSite ** just do link checking on the "build/site" directory * checkBareBonesHtml ** depend on buildBareBones _and the "solr" and "lucene" level javadoc tasks_ ** just do link checking on the "build/bare-bones" directory Does that make sense? The one caveat being: since jekyll *is* now easy to run in gradle, we don't need to build a "bare-bones" version directly with asciidoctor (see SOLR-14824), but conceptually the two different "buildFoo" tasks – and their distinct output dirs – still make sense: (ie: buildSite vs buildLocalCopyOfSiteForJavadocLinkValiation; checkSite vs checkLocalCopyOfSiteForJavadocLinkValiation) {quote}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. {quote} Yep yep ... i think we're on the same page, and you just gave me the final missing piece I didn't really understand before, which i never really articulated well: how the ref-guide could indicate that it's "check" task depended on the output of the top level "documentation" > 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