[
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: [email protected]
For additional commands, e-mail: [email protected]
