[
https://issues.apache.org/jira/browse/LUCENE-9201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17034392#comment-17034392
]
Robert Muir commented on LUCENE-9201:
-------------------------------------
I have a proposal that maybe works better. I'll write it again for the 2nd time
(JIRA's bugs are super annoying, i just clicked "Visual" to preview all that i
had written and all my content totally disappeared: so here i am typing it
again).
Let's consider the simplest case: lucene {{core}} and {{demo}} modules.
BUILDING DEMO MODULE
In the current ant build, {{demo}}'s javadocs task depends on {{core}}'s
javadocs task.
But I think strictly all that is necessary is {{core}}'s *package list*
(element-list file), which can be done simpler and faster?
{noformat}
org.apache.lucene
org.apache.lucene.analysis
org.apache.lucene.analysis.standard
org.apache.lucene.analysis.tokenattributes
org.apache.lucene.codecs
org.apache.lucene.codecs.blocktree
...
{noformat}
This means fixing the gradle offline logic for the JDK too. It needs to match
ant and have JDK "package-list", so that it knows which packages should link to
the JDK site, vs which ones should link somewhere else. This is also missing
from the gradle build today, just another thing to fix.
STRUCTURING DOCS
In the current ant build, we have:
{{noformat}}
build/docs/core/index.html
build/docs/demo/index.html
{{noformat}}
The {{docs}} folder is uploaded to the website when releasing.
Instead I propose we upload a structure that reflects the source-code
structure. It would instead be:
{{noformat}}
demo/build/docs/javadoc/index.html
core/build/docs/javadoc/index.html
{{noformat}}
Because generated docs would not be in one folder but instead spread across
many folders, we'd need some basic tooling to help get it to the website. We
would also have to adjust all the explicit links (see my comment above), but
there are not that many of them.
LINTING DOCS
For running the "documentation-lint" check, today this is not a per-module task.
I think it should be renamed "checkDocumentationLinks" or something like that.
All it would do is validate hyperlinks between pieces of the documentation, to
keep this top-level task minimal. All other checks should be moved to
per-module (ideally done with the {{javadoc}} tool itself).
> Port documentation-lint task to Gradle build
> --------------------------------------------
>
> Key: LUCENE-9201
> URL: https://issues.apache.org/jira/browse/LUCENE-9201
> Project: Lucene - Core
> Issue Type: Sub-task
> Affects Versions: master (9.0)
> Reporter: Tomoko Uchida
> Assignee: Tomoko Uchida
> Priority: Major
> Attachments: javadocGRADLE.png, javadocHTML4.png, javadocHTML5.png
>
> Time Spent: 50m
> Remaining Estimate: 0h
>
> Ant build's "documentation-lint" target consists of those two sub targets.
> * "-ecj-javadoc-lint" (Javadoc linting by ECJ)
> * "-documentation-lint"(Missing javadocs / broken links check by python
> scripts)
--
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
