[jira] [Commented] (SOLR-12134) validate links to javadocs in ref-guide & hook all ref-guide validation into top level documentation/precommit

["Hoss Man (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-12134?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16408244#comment-16408244 ] 

Hoss Man commented on SOLR-12134:
---------------------------------

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
>
> 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org