[
https://issues.apache.org/jira/browse/SOLR-12134?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16408244#comment-16408244
]
Hoss Man edited comment on SOLR-12134 at 3/21/18 6:03 PM:
----------------------------------------------------------
I think we should make 2 broad changes to the build, which i've been testing
out in a patch...
# add a optional sys prop when building the ref guide to use
{{local.javadocs}} paths in the html versions of the guide
** when using {{local.javadocs}} the CheckLinksAndAnchors code will also
validate that any javadoc file mentioned in the ref-guide exists locally – so
you have to have built all javadocs to use it
** The PDF will never use local javadocs paths, always absolute urls on
lucene.apache.org
# update {{cd solr; ant documentation}} to also build the pdf (and
bare-bones-html) versions of the guide using this {{local.javadocs}} option
** This will ensure that both {{ant precommit}} and any jenkins job that
builds documentation will fail if someone breaks the ref-guide (either
directly, or by changing javadocs in a way that will break the ref-guide)
Things that won't change...
* if you run {{cd solr/solr-ref-guide; ant <any-target>}} it should still work
exactly as before
** intra ref-guide links will still be validated
** links to javadocs will still use absolute URLs...
*** you won't know if they are broken – but on the flip side you can rapidly
rebuild the ref-guide w/o needing to build all lucene/solr javadocs
* the release process for either lucene/solr or the ref-guide stays the same
*
** In general this moves us closer to having a unified release process, but
it's not all the way there
** Notable: the "official builds" of the ref-guide (both in PDF and the hosted
HTML) will still use absolute URLs to link to javadocs
----
Some examples...
{code:java}
cd solr/solr-ref-guide
ant build-site # no change from existing behavior
ant bare-bones-html-validation # no change from existing behavior
ant build-pdf # no change from existing behavior
ant build-site -Dlocal.javadocs=true # local jekyll build will now link to
local
# javadoc files and build will fail if
any/all javadoc
# links don't exist
{code}
{code:java}
cd solr
ant documentation # now builds PDF & validates barebones html ref-guide
# (after building javadocs) to ensure no fatal PDF
# errors or broken links
{code}
{code:java}
ant precommit # now builds & validates barebones html ref-guide after
building javadocs
{code}
----
The attached patch makes this all work (including a fix to an existing link in
{{solr-tutorial.adoc}} which currently depends on some weird rewrite rule
behavior to work). If you also apply the
"nocommit.SOLR-12134.sample-failures.patch" file you can see how some various
examples of problems will affect things like {{cd solr/solr-ref-guide; ant}} vs
{{cd solr; ant documentation}} (Of course: to test {{ant precommit}} you'll
have to remove the 'nocommit' test from that patch, since it will cause
precommit to fail fast before it even tries to build documentation)
(*EDIT* – based on an offline question from steve, i updated one comment in the
examples above to clarify that {{ant documentation}} will actually build the
pdf _and_ validate the links by building & verifying the bare-bones html ...
that's a preexisting dependency in {{build-pdf)}}
was (Author: hossman):
I think we should make 2 broad changes to the build, which i've been testing
out in a patch...
# add a optional sys prop when building the ref guide to use
{{local.javadocs}} paths in the html versions of the guide
** when using {{local.javadocs}} the CheckLinksAndAnchors code will also
validate that any javadoc file mentioned in the ref-guide exists locally – so
you have to have built all javadocs to use it
** The PDF will never use local javadocs paths, always absolute urls on
lucene.apache.org
# update {{cd solr; ant documentation}} to also build the pdf (and
bare-bones-html) versions of the guide using this {{local.javadocs}} option
** This will ensure that both {{ant precommit}} and any jenkins job that
builds documentation will fail if someone breaks the ref-guide (either
directly, or by changing javadocs in a way that will break the ref-guide)
Things that won't change...
* if you run {{cd solr/solr-ref-guide; ant <any-target>}} it should still work
exactly as before
** intra ref-guide links will still be validated
** links to javadocs will still use absolute URLs...
*** you won't know if they are broken – but on the flip side you can rapidly
rebuild the ref-guide w/o needing to build all lucene/solr javadocs
* the release process for either lucene/solr or the ref-guide stays the same
** In general this moves us closer to having a unified release process, but
it's not all the way there
** Notable: the "official builds" of the ref-guide (both in PDF and the hosted
HTML) will still use absolute URLs to link to javadocs
----
Some examples...
{code:java}
cd solr/solr-ref-guide
ant build-site # no change from existing behavior
ant bare-bones-html-validation # no change from existing behavior
ant build-pdf # no change from existing behavior
ant build-site -Dlocal.javadocs=true # local jekyll build will now link to
local
# javadoc files and build will fail if
any/all javadoc
# links don't exist
{code}
{code:java}
cd solr
ant documentation # now builds & validates barebones html ref-guide after
building javadocs
{code}
{code:java}
ant precommit # now builds & validates barebones html ref-guide after
building javadocs
{code}
----
The attached patch makes this all work (including a fix to an existing link in
{{solr-tutorial.adoc}} which currently depends on some weird rewrite rule
behavior to work). If you also apply the
"nocommit.SOLR-12134.sample-failures.patch" file you can see how some various
examples of problems will affect things like {{cd solr/solr-ref-guide; ant}} vs
{{cd solr; ant documentation}} (Of course: to test {{ant precommit}} you'll
have to remove the 'nocommit' test from that patch, since it will cause
precommit to fail fast before it even tries to build documentation)
> validate links to javadocs in ref-guide & hook all ref-guide validation into
> top level documentation/precommit
> --------------------------------------------------------------------------------------------------------------
>
> Key: SOLR-12134
> URL: https://issues.apache.org/jira/browse/SOLR-12134
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Hoss Man
> Assignee: Hoss Man
> Priority: Major
> Attachments: SOLR-12134.patch,
> nocommit.SOLR-12134.sample-failures.patch
>
>
> We've seen a couple problems come up recently where the ref-guide had broken
> links ot javadocs.
> In some cases these are because people made typos in java classnames /
> pathnames while editing the docs - but in other cases the problems were that
> the docs were correct at one point, but then later the class was
> moved/renamed/removed, or had it's access level downgraded from public to
> private (after deprecation)
> I've worked up a patch with some ideas to help us catch these types of
> mistakes - and in general to hook the "bare-bones HTML" validation (which
> does not require jekyll or any non-ivy managed external dependencies) into
> {{ant precommit}}
> Details to follow in comment/patch...
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
