[jira] [Updated] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Chris M. Hostetter updated SOLR-14824:
--
Attachment: SOLR-14824.patch
Status: Open (was: Open)
{quote}This looks weird (and comment is inconsistent with code).
{quote}
Ah, yeah – that comment was (obtusely) trying to explain that for the "X.Y" ref
guide we always link to the javadocs of the "X.Y.0" release. I've beefed up the
comments on the version & path variables to make it more clear their purpose &
"style" of values each one contains.
{quote}If this draft status is related to version then it could be
automatically detected (version.contains("SNAPSHOT")).
{quote}
That wouldn't work because by default 'version' (in the top level build.gradle
file) always contains the SNAPSHOT suffix by default (unless 'version.release'
or 'version.suffix' is overriden on the command line.)
The usecase here is that on "branch_9_7" regardless of whether 'baseVersion' is
9.7.0, or 9.7.1, etc... (making the default "version" 9.7.0-SNAPSHOT,
9.7.1-SNAPSHOT, etc..), we want to be able to "build" the "9.7" ref-guide, and
by default the builds should be "\-DRAFT" but optionally a committer should be
able to indicate that it's "non-DRAFT" so they can (re-)publish it to the site.
I suppose instead of using {{\-PsolrGuideDraft=false}} we could document that
the way to build an "non-DRAFT" copy of the guide is to use
{{\-Dversion.suffix=''}} ? ... but the approach in the patch seems easier for
the actual usecase/workflow/process of building & publishing the ref-guide.
(If/When we get to the point of wanting to build & publishing the ref-guide
automatically on every release, then it might make sense to drive the 'DRAFT"
behavior based on wether 'version' has a suffix on it – but let's cross that
bridge when we come to it)
{quote}For this issue I was mainly looking at the solrRootPath property that's
obviously not a relative URL ...
{quote}
Oh, sure – yeah. I fixed that to be based on {{project(':solr')}}
{quote}I think the changes to build.gradle that remove the asciidocAttrs
section are going to cause some unexpected consequences. There are a couple
parameters defined there that aren't in _config.yml.template, specifically:
{quote}
Those attributes have never affected the jekyll build: they've only ever been
used when gradle/ant ran asciidoctor directly for the bare-bones (and PDF)
builds. The ant build.xml file actually had a comment pointing out this
distinction, and I'm pretty sure the reason for that choice was because of how
jekyll uses asciidoctor slightly differently (for things like TOC), and they
were only needed by PDF renderer?
"attribute-missing" and "icons" are actually hard coded in
{{_config.yml.template}} (with those same values) but only in the "asciidoctor
> attributes" section, not in the "solr-attributes" YAML reference, so they
can't mistakenly be used as variables inside of content or in liquid
templates...
{noformat}
attributes:
<<: *solr-attributes-ref
attribute-missing: "warn"
icons: "font"
source-highlighter: "rouge"
rouge-theme: "thankful-eyes"
stem:
{noformat}
...if you think we should add the other 4 we can do that, but we should take
care and review the output carefully since they may (probably?) change the
look/feel of the content from what we currently get on master/8x since they
haven't been used in the jekyll builds up to now.
{quote}I couldn't get the patch to apply so can't check these but they're worth
a look.
{quote}
there were conflicts introduced by the removal of velocity ... the patching i'm
attaching now should apply clean.
> Simplify set of Ref Guide build parameters
> --
>
> Key: SOLR-14824
> URL: https://issues.apache.org/jira/browse/SOLR-14824
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: Build, documentation
>Reporter: Cassandra Targett
>Assignee: Chris M. Hostetter
>Priority: Minor
> Attachments: SOLR-14824.patch, SOLR-14824.patch, SOLR-14824.patch
>
>
> While trying to solve LUCENE-9495, I thought it might be a good idea to try
> to simplify the set of variables and properties used during the Ref Guide
> build.
> There are 3 areas to work on:
> 1. Remove the "barebones-html" build. With Gradle the build is self-contained
> and {{gradlew check}} and {{gradle precommit}} could just build the full docs
> and check them.
> 2. Remove some properties that only existed for a hypothetical need related
> to the now-removed PDF.
> 3. Change remaining properties to be defined directly in build.gradle instead
> of relying on ant properties functionality.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---
[jira] [Updated] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Chris M. Hostetter updated SOLR-14824:
--
Attachment: SOLR-14824.patch
Assignee: Chris M. Hostetter
Status: Open (was: Open)
{quote}Next Steps: ...
{quote}
Updated patch includes those outstanding items with a slightly tweaked property
name.
Final syntax with patch applied (as documented in meta-docs/publish.adoc) ...
{noformat}
# build the "DRAFT" guide over and over as much as you want as things change...
./gradlew solr:solr-ref-guide:buildSite
# build the "real" site for final publishing...
./gradlew solr:solr-ref-guide:buildSite -PsolrGuideDraft=false
{noformat}
FWIW, based on the conversations in SOLR-14870 I was thinking that instead of a
command line property to control the "DRAFT" status, we should instead really
just have "buildSite" which would always build the "real" (ie: never a DRAFT)
site into build/html-site, while some new "buildLocalGuide" would always build
the "DRAFT" pages (and use relative links to "local" javadocs for validation -
see discussion in SOLR-14870) and the "default" gradle task / workflow should
be to run the "buildLocalGuide" task – leaving "buildSite" as something only
the a committer would run when publishing the site.
BUT ... then i thought about the actaul publishing workflow (as documented in
meta-docs/publish.adoc ) and the fact that we do currently "publish" DRAFT
copies of the site to lucene.apache.org for people to review – up until the
solr release is "final" at which point we publish the "non-draft" version of
the guide
So for now i left in the {{-PsolrGuideDraft=false}} propety ... but it's
something we may want to reconsider down the road?
[~ctargett] how does this patch look to you? are there anything you had in mind
for simplification/clean up that i overlooked?
> Simplify set of Ref Guide build parameters
> --
>
> Key: SOLR-14824
> URL: https://issues.apache.org/jira/browse/SOLR-14824
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: Build, documentation
>Reporter: Cassandra Targett
>Assignee: Chris M. Hostetter
>Priority: Minor
> Attachments: SOLR-14824.patch, SOLR-14824.patch
>
>
> While trying to solve LUCENE-9495, I thought it might be a good idea to try
> to simplify the set of variables and properties used during the Ref Guide
> build.
> There are 3 areas to work on:
> 1. Remove the "barebones-html" build. With Gradle the build is self-contained
> and {{gradlew check}} and {{gradle precommit}} could just build the full docs
> and check them.
> 2. Remove some properties that only existed for a hypothetical need related
> to the now-removed PDF.
> 3. Change remaining properties to be defined directly in build.gradle instead
> of relying on ant properties functionality.
--
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
[jira] [Updated] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Chris M. Hostetter updated SOLR-14824:
--
Attachment: SOLR-14824.patch
Status: Open (was: Open)
Starting point:
* rip out all "bare bones" related stuff
* change the "template" style to use groovy ScriptTemplateEngine convention
** eliminating hte need for a dummyAntProject
* reduce down the set of properties we need/replace
** move any that are only needed in the map so that they are *only* inited in
the map
Next Steps:
* rip out "solrGuideVersion" / "solr-guide-version"
** replace usages of "solr-guide-version" in templates with "solr-docs-version"
* change command line syntax to be {{-Pdraft=true|false}} (defaulting to true)
> Simplify set of Ref Guide build parameters
> --
>
> Key: SOLR-14824
> URL: https://issues.apache.org/jira/browse/SOLR-14824
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: Build, documentation
>Reporter: Cassandra Targett
>Priority: Minor
> Attachments: SOLR-14824.patch
>
>
> While trying to solve LUCENE-9495, I thought it might be a good idea to try
> to simplify the set of variables and properties used during the Ref Guide
> build.
> There are 3 areas to work on:
> 1. Remove the "barebones-html" build. With Gradle the build is self-contained
> and {{gradlew check}} and {{gradle precommit}} could just build the full docs
> and check them.
> 2. Remove some properties that only existed for a hypothetical need related
> to the now-removed PDF.
> 3. Change remaining properties to be defined directly in build.gradle instead
> of relying on ant properties functionality.
--
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
