[jira] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17200254#comment-17200254
]
Chris M. Hostetter edited comment on SOLR-14824 at 9/22/20, 5:23 PM:
-
Sorry Uwe, that's what I get for following your advice and using the projectDir
{{:)}}
I created SOLR-14889 with an idea for a better general purpose fix.
was (Author: hossman):
Sorry Uwe, that's what I get for following your advice and using the productDir
{{:)}}
I created SOLR-14889 with an idea for a better general purpose fix.
> 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
> Fix For: master (9.0)
>
> 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)
-
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
[jira] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17198936#comment-17198936
]
Uwe Schindler edited comment on SOLR-14824 at 9/20/20, 9:02 AM:
Ignore my last comment, now it seems to work. I pressed Ctrl-C while
downloading the GEMS and left the build/.gem folder in inconsistent state.
was (Author: thetaphi):
Ignore my last comment, now it seems to work. I pressed Ctrl-C while
downloading the EMS and left the build/.gem folder in inconsistent state.
> 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
> Fix For: master (9.0)
>
> 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)
-
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
[jira] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17198467#comment-17198467
]
Chris M. Hostetter edited comment on SOLR-14824 at 9/18/20, 5:23 PM:
-
{quote}Think this way: even if somebody doesn't know about the ref guide and
runs top-level "assemble everything in version X" then the guide would be
compiled with an appropriate non-version status. Does this make sense?
{quote}
(NOTE: I'm going to assume "non-version" was a typo/brain-fart and you meant
"non-DRAFT" because otherwise i really have no idea what you ment)
I'm don't think what you're suggesting really makes sense in terms of the
ref-guide – because when you talk about "release procedure" and "version X"
what you're talking about is "ARTIFACT release procedure" and "version X.Y.Z" –
where the artifacts are uploaded to dist.apache, frozen and immutable and the
only way to "update" them is to do a new release of X.Y.(Z+1).
But for the ref-guide we don't have "released" artifacts that are frozen in
time (we use to, we stoped, and cleaning up the build cruft related to them is
a big part of this issue) – we might "publish" (to the website) a non-draft
"ref-guide X.Y" to the website, and then a week, or a month later someone might
notice a very missleading mistake, or typo in the markup that causes a
malformed and unreadable example, and we might fix that on branch_X_Y and
republish "ref-guide X.Y" to the exact same URL on the website ... and that
would all be independent of whether there has been a "release" of Solr X.Y.1,
or X.Y.2, etc... from that branches in the mean time.
Even if someone doesn't know about the ref-guide, but they checkout the the
release commit/tag for "X.Y.0" and run the "assemble everything" (setting
whatever property they may need to set to mark it as 'official' and
'non-SNAPSHOT') that doesn't mean the ref-guide they find in the build
directory should be a 'non-DRAFT' "ref-guide X.Y" because there may be
corrected content for "guide version X.Y" on branch_X_Y _after_ that release
commit.
To go back to your question from the other day, which i realize I responded to
but didn't directly answer..
{quote}If this draft status is related to version then it could be
automatically detected (version.contains("SNAPSHOT")).
{quote}
No. The "draft status" is not related to the version. Not in the sense of the
'$version' variable in the top level build.gradle (either hardcoded or derived
from commad line props), nor in the sense of the '$solrDocsVersion' variable in
the ref-guide build (with the patch applied).
The only thing that determines whether a ref-guide build is a DRAFT or not, is
if it is currently being built by a committer, who has the intent of uploading
it to the website and considers the content to no longer be DRAFT.
was (Author: hossman):
{quote}Think this way: even if somebody doesn't know about the ref guide and
runs top-level "assemble everything in version X" then the guide would be
compiled with an appropriate non-version status. Does this make sense?
{quote}
(NOTE: I'm going to assume "non-version" was a typo/brain-fart and you meant
"non-DRAFT" because otherwise i really have no idea what you ment)
I'm don't think what you're suggesting really makes sense in terms of the
ref-guide – because when you talk about "release procedure" and "version X"
what you're talking about is "ARTIFACT release procedure" and "version X.Y.Z" –
where the artifacts are uploaded to dist.apache, frozen and immutable and the
only way to "update" them is to do a new release of X.Y.(Z+1).
But for the ref-guide we don't have "released" artifacts that are frozen in
time (we use to, we stoped, and cleaning up the build cruft related to them is
a big part of this issue) – we might "publish" (to the website) a non-draft
"ref-guide X.Y" to the website, and then a week, or a month later someone might
notice a very missleading mistake, or typo in the markup that causes a
malformed and unreadable example, and we might fix that on branch_X_Y and
republish "ref-guide X.Y" to the exact same URL on the website ... and that
would all be independent of whether there has been a "release" of Solr X.Y.1,
or X.Y.0, etc... from that branches in the mean time.
Even if someone doesn't know about the ref-guide, but they checkout the the
release commit/tag for "X.Y.0" and run the "assemble everything" (setting
whatever property they may need to set to mark it as 'official' and
'non-SNAPSHOT') that doesn't mean the ref-guide they find in the build
directory should be a 'non-DRAFT' "ref-guide X.Y" because there may be
corrected content for "guide version X.Y" on branch_X_Y _after_ that release
commit.
To go back to your question from the other day, which i realize I responded to
but didn't directly answer..
{quote}If this draft status is related to
[jira] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17197570#comment-17197570
]
Uwe Schindler edited comment on SOLR-14824 at 9/17/20, 9:49 AM:
Hi Hoss,
bq. Hmmm i don't really feel comfortable trying to tackle those changes
here/now – let's pursue this idea more in SOLR-14870 – because AFAICT those
productDir/buildDir variables return absolute file paths
For this issue I was mainly looking at the {{solrRootPath}} property that's
obviously not a relative URL path, which highly depends on structure of build
system (what happens if the CWD is different when executing the scripts in
later Gradle versions?). The series of ".." makes it completely unclear how it
is used. For the URLs to javadocs folders, I agree that's more the SOLR-14870
issue.
bq. but i'm assuming we could relativize those paths again the ref-guides own
buildDir
of course, instead of calling toUri(), you can do {{Path#relativize()}}, using
the own projects buildDir / output dir in combination with the code shown
above. As you need this as URI path later, don't forget to convert
operating-system specific slashes to forward slashes. See example here:
https://github.com/apache/lucene-solr/blob/master/gradle/documentation/render-javadoc.gradle#L500
{{def relative = pathFrom.relativize(pathTo).toString().replace(File.separator,
'/')}}
Also make sure that both directories EXIST before calling relativize, otherwise
the result is undefined (operating system dependent). So before calculating
relative path make sure to call mkdir. So calculating of relative paths must be
done not during gradle configuration phase (where no folders exist yet), but
during the execution of task. So possibly do this in the task's {{doFirst()}},
before executing the asciidoctor/... scripts.
Uwe
was (Author: thetaphi):
Hi Hoss,
bq. Hmmm i don't really feel comfortable trying to tackle those changes
here/now – let's pursue this idea more in SOLR-14870 – because AFAICT those
productDir/buildDir variables return absolute file paths
For this issue I was mainly looking at the {{solrRootPath}} property that's
obviously not a relative URL path, which highly depends on structure of build
system (what happens if the CWD is different when executing the scripts in
later Gradle versions?). The series of ".." makes it completely unclear how it
is used. For the URLs to javadocs folders, I agree that's more the SOLR-14870
issue.
bq. but i'm assuming we could relativize those paths again the ref-guides own
buildDir
of course, instead of calling toUri(), you can do {{Path#relativize()}}, using
the own projects buildDir / output dir in combination with the code shown
above. As you need this as URI path later, don't forget to convert
operating-system specific slashes to forward slashes. See example here:
https://github.com/apache/lucene-solr/blob/master/gradle/documentation/render-javadoc.gradle#L500
{{def relative = pathFrom.relativize(pathTo).toString().replace(File.separator,
'/')}}
Also make sure that both directories EXIST before calling relativize, otherwise
the result is undefined (operating system dependent). So before calculating
relative path make sure to call mkdir.
Uwe
> 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] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17197570#comment-17197570
]
Uwe Schindler edited comment on SOLR-14824 at 9/17/20, 9:46 AM:
Hi Hoss,
bq. Hmmm i don't really feel comfortable trying to tackle those changes
here/now – let's pursue this idea more in SOLR-14870 – because AFAICT those
productDir/buildDir variables return absolute file paths
For this issue I was mainly looking at the {{solrRootPath}} property that's
obviously not a relative URL path, which highly depends on structure of build
system (what happens if the CWD is different when executing the scripts in
later Gradle versions?). The series of ".." makes it completely unclear how it
is used. For the URLs to javadocs folders, I agree that's more the SOLR-14870
issue.
bq. but i'm assuming we could relativize those paths again the ref-guides own
buildDir
of course, instead of calling toUri(), you can do {{Path#relativize()}}, using
the own projects buildDir / output dir in combination with the code shown
above. As you need this as URI path later, don't forget to convert
operating-system specific slashes to forward slashes. See example here:
https://github.com/apache/lucene-solr/blob/master/gradle/documentation/render-javadoc.gradle#L500
{{def relative = pathFrom.relativize(pathTo).toString().replace(File.separator,
'/')}}
Also make sure that both directories EXIST before calling relativize, otherwise
the result is undefined (operating system dependent). So before calculating
relative path make sure to call mkdir.
Uwe
was (Author: thetaphi):
Hi Hoss,
bq. Hmmm i don't really feel comfortable trying to tackle those changes
here/now – let's pursue this idea more in SOLR-14870 – because AFAICT those
productDir/buildDir variables return absolute file paths
For this issue I was mainly looking at the {{solrRootPath}} property that's
obviously not a relative URL path, which highly depends on structure of build
system (what happens if the CWD is different when executing the scripts in
later Gradle versions?). The series of ".." makes it completely unclear how it
is used. For the URLs to javadocs folders, I agree that's more the SOLR-14870
issue.
bq. but i'm assuming we could relativize those paths again the ref-guides own
buildDir
of course, instead of calling toUri(), you can do {{Path#relativize()}}, using
the own projects buildDir / output dir in combination with the code shown
above. As you need this as URI path later, don't forget to convert
operating-system specific slashes to forward slashes. See example here:
https://github.com/apache/lucene-solr/blob/master/gradle/documentation/render-javadoc.gradle#L500
{{def relative = pathFrom.relativize(pathTo).toString().replace(File.separator,
'/')}}
Uwe
> 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] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17197481#comment-17197481
]
Uwe Schindler edited comment on SOLR-14824 at 9/17/20, 8:13 AM:
bq. (also, FWIW, trying to call toURI on project(':lucene').buildDir.toPath()
or project(':lucene').buildDir.toPath().resolve('documentation') kept giving me
a weird groovy error i couldn't make heads of tails of:
It's toUri(), my fault:
[https://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html#toUri()]
The Gradle error messages during compilation are often a bit crazy, not sure
why. Often it shows a followup error instead of the original error.
was (Author: thetaphi):
bq. (also, FWIW, trying to call toURI on project(':lucene').buildDir.toPath()
or project(':lucene').buildDir.toPath().resolve('documentation') kept giving me
a weird groovy error i couldn't make heads of tails of:
It's toUri(), my fault:
https://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html#toUri()
> 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] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17197265#comment-17197265
]
Uwe Schindler edited comment on SOLR-14824 at 9/16/20, 10:36 PM:
-
Hi Hoss,
looks fine to me in general, but I'd change a bit those crazy settings:
{{solrRootPath: '../../../../solr/',}}
This is a bit strange to read, it would be much cleaner to use gradle's ability
to know where the files are without relying on the project directory layout,
like {{project(':solr').projectDir}}
The same applies to the "localJavadocs" folders (see SOLR-14870). There you can
also use something like:
{{project(':lucene').buildDir.toPath().resolve('documentation').toURI().toAsciiString()}},
which returns an URL/URI that can be used inside HTML as links and would
resolve to the "site/global" javadocs of Lucene.
was (Author: thetaphi):
Hi Hoss,
looks fine to me in general, but I'd change a bit those crazy settings:
{{solrRootPath: '../../../../solr/',}}
This is a bit strange to read, it would be much cleaner to use gradle's ability
to know where the files are without relying on the project directory layout,
like {{project(':solr').projectDir}}
The same applies to the "localJavadocs" folders (see SOLR-14870).
> 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] [Comment Edited] (SOLR-14824) Simplify set of Ref Guide build parameters
[
https://issues.apache.org/jira/browse/SOLR-14824?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17197265#comment-17197265
]
Uwe Schindler edited comment on SOLR-14824 at 9/16/20, 10:34 PM:
-
Hi Hoss,
looks fine to me in general, but I'd change a bit those crazy settings:
{{solrRootPath: '../../../../solr/',}}
This is a bit strange to read, it would be much cleaner to use gradle's ability
to know where the files are without relying on the project directory layout,
like {{project(':solr').projectDir}}
The same applies to the "localJavadocs" folders (see SOLR-14870).
was (Author: thetaphi):
Hi Hoss,
looks fine to me in general, but I'd change a bit those crazy settings:
{{solrRootPath: '../../../../solr/',}}
This is a bit strange to read, it would be much cleaner to use gradle's ability
to know where the files are without relying on the project directory layout,
like {{$project(':solr').projectDir}}
The same applies to the "localJavadocs" folders (see SOLR-14870).
> 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
