From 108f5d123aa1145ce8800004459002efaddf59a4 Mon Sep 17 00:00:00 2001 From: AndyChen Date: Tue, 23 Jan 2024 19:33:33 +0800 Subject: [PATCH] chore: Temporarily disable the license report generation to speed up build (#704) * fix: using project/index generator * fix: broken link * chore: reformat code * simplify generator and build fixes * additional documentation clarify * code format chore * chore: reducing cr cost * chore: remove unnecessary * reset link configuration * keep index doc * disable license report by default * reduce license because disable by default * Change the description of build paradox * chore: code fmt --- .github/workflows/link-validator.yml | 2 +- .github/workflows/publish-1.0-docs.yml | 2 +- .github/workflows/publish-1.0-nightly.yml | 2 +- .github/workflows/publish-nightly.yml | 2 +- CONTRIBUTING.md | 12 +++ build.sbt | 1 + docs/src/main/paradox/index.md | 2 +- .../project/{index.md => project-index.md} | 12 +-- project/Paradox.scala | 8 +- project/PekkoBuild.scala | 5 +- project/ProjectIndexGenerator.scala | 75 +++++++++++++++++++ 11 files changed, 106 insertions(+), 17 deletions(-) rename docs/src/main/paradox/project/{index.md => project-index.md} (58%) create mode 100644 project/ProjectIndexGenerator.scala diff --git a/.github/workflows/link-validator.yml b/.github/workflows/link-validator.yml index 6eab739c23..2c6694bba7 100644 --- a/.github/workflows/link-validator.yml +++ b/.github/workflows/link-validator.yml @@ -35,7 +35,7 @@ jobs: uses: coursier/setup-action@v1.3.3 - name: Create the Pekko site - run: sbt -Dpekko.genjavadoc.enabled=true "Javaunidoc/doc; Compile/unidoc; docs/paradox" + run: sbt -Dpekko.genjavadoc.enabled=true -Dpekko.genlicensereport.enabled=true "Javaunidoc/doc; Compile/unidoc; docs/paradox" - name: Run Link Validator run: cs launch net.runne::site-link-validator:0.2.2 -- scripts/link-validator.conf diff --git a/.github/workflows/publish-1.0-docs.yml b/.github/workflows/publish-1.0-docs.yml index 590e1c8ec6..773b7a7e0f 100644 --- a/.github/workflows/publish-1.0-docs.yml +++ b/.github/workflows/publish-1.0-docs.yml @@ -55,7 +55,7 @@ jobs: # TODO come up with a better way to control the version, possibly based on git tags - name: Build Documentation run: |- - sbt -Dpekko.genjavadoc.enabled=true "set ThisBuild / version := \"1.0.2\"; docs/paradox; unidoc" + sbt -Dpekko.genjavadoc.enabled=true -Dpekko.genlicensereport.enabled=true "set ThisBuild / version := \"1.0.2\"; docs/paradox; unidoc" # Create directory structure upfront since rsync does not create intermediate directories otherwise - name: Create directory structure diff --git a/.github/workflows/publish-1.0-nightly.yml b/.github/workflows/publish-1.0-nightly.yml index 1c39c3c1e9..1a53b500eb 100644 --- a/.github/workflows/publish-1.0-nightly.yml +++ b/.github/workflows/publish-1.0-nightly.yml @@ -65,4 +65,4 @@ jobs: - name: Build Documentation run: |- - sbt -Dpekko.genjavadoc.enabled=true docs/paradox unidoc + sbt -Dpekko.genjavadoc.enabled=true -Dpekko.genlicensereport.enabled=true docs/paradox unidoc diff --git a/.github/workflows/publish-nightly.yml b/.github/workflows/publish-nightly.yml index 1e4c7f953d..2d9193079b 100644 --- a/.github/workflows/publish-nightly.yml +++ b/.github/workflows/publish-nightly.yml @@ -64,7 +64,7 @@ jobs: - name: Build Documentation run: |- - sbt -Dpekko.genjavadoc.enabled=true docs/paradox unidoc + sbt -Dpekko.genjavadoc.enabled=true -Dpekko.genlicensereport.enabled=true docs/paradox unidoc # Create directory structure upfront since rsync does not create intermediate directories otherwise - name: Create nightly directory structure diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbf52b8075..dcb4ce3a8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -346,6 +346,18 @@ sbt -Dpekko.genjavadoc.enabled=true Javaunidoc/doc Which will generate JavaDoc style docs in `./target/javaunidoc/index.html`. This requires a JDK version 11 or later. +#### Changing the project information page index + +In case you want to change the index of `Project Information` page, you need to change it on the +`project/ProjectIndexGenerator.scala` so it can be included in the automatic docs generation. + +#### License Report Generation + +By default, license report generation is disabled to improve compilation speed. You can enable it by configuring `-Dpekko.genlicensereport.enabled=true`. e.g.: + +- `sbt -Dpekko.genlicensereport.enabled=true "docs/paradox"` +- `sbt -Dpekko.genlicensereport.enabled=true shell` And then `docs/paradox` + ### External dependencies All the external runtime dependencies for the project, including transitive dependencies, must have an open source license that is equal to, or compatible with, [Apache 2](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/build.sbt b/build.sbt index 22c0ddcca9..0695708bfb 100644 --- a/build.sbt +++ b/build.sbt @@ -257,6 +257,7 @@ lazy val docs = pekkoModule("docs") PekkoParadoxPlugin, NoPublish, ParadoxBrowse, + ProjectIndexGenerator, ScaladocNoVerificationOfDiagrams, StreamOperatorsIndexGenerator, Jdk9) diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md index 9aa348384b..1a37c703fd 100644 --- a/docs/src/main/paradox/index.md +++ b/docs/src/main/paradox/index.md @@ -17,7 +17,7 @@ * [index-utilities](index-utilities.md) * [common/other-modules](common/other-modules.md) * [additional/deploy](additional/deploy.md) -* [project/index](project/index.md) +* [project/index](project/project-index.md) * [classic](index-classic.md) @@@ diff --git a/docs/src/main/paradox/project/index.md b/docs/src/main/paradox/project/project-index.md similarity index 58% rename from docs/src/main/paradox/project/index.md rename to docs/src/main/paradox/project/project-index.md index a640428cf7..08b4cb3370 100644 --- a/docs/src/main/paradox/project/index.md +++ b/docs/src/main/paradox/project/project-index.md @@ -1,3 +1,4 @@ + # Project Information @@toc { depth=2 } @@ -8,16 +9,15 @@ * [scala3](scala3.md) * [downstream-upgrade-strategy](downstream-upgrade-strategy.md) * [../common/may-change](../common/may-change.md) -* [ide] (../additional/ide.md) -* [lombok](immutable.md) -* [osgi](../additional/osgi.md) +* [../additional/ide](../additional/ide.md) +* [immutable](immutable.md) +* [../additional/osgi](../additional/osgi.md) * [migration-guides](migration-guides.md) * [rolling-update](rolling-update.md) * [issue-tracking](issue-tracking.md) * [licenses](licenses.md) -* [license-report](license-report.md) -* [faq](../additional/faq.md) -* [books](../additional/books.md) +* [../additional/faq](../additional/faq.md) +* [../additional/books](../additional/books.md) * [examples](examples.md) * [links](links.md) diff --git a/project/Paradox.scala b/project/Paradox.scala index 4245461808..3fe2b5c377 100644 --- a/project/Paradox.scala +++ b/project/Paradox.scala @@ -95,10 +95,10 @@ object Paradox { lazy val sourceGeneratorSettings = Seq( Compile / paradoxMarkdownToHtml / sourceGenerators += Def.taskDyn { val targetFile = (Compile / paradox / sourceManaged).value / "project" / "license-report.md" - - (LocalRootProject / dumpLicenseReportAggregate).map { dir => - IO.copy(List(dir / "pekko-root-licenses.md" -> targetFile)).toList - } + ProjectIndexGenerator.CliOptions.generateLicenseReportEnabled.ifTrue( + (LocalRootProject / dumpLicenseReportAggregate).map { dir => + IO.copy(List(dir / "pekko-root-licenses.md" -> targetFile)).toList + }).orElse(Some(Def.task(List.empty[File]))).get }.taskValue) lazy val settings = diff --git a/project/PekkoBuild.scala b/project/PekkoBuild.scala index 94445d810f..fd8bcc70fc 100644 --- a/project/PekkoBuild.scala +++ b/project/PekkoBuild.scala @@ -308,8 +308,9 @@ object PekkoBuild { UsefulTask("sortImports", "Sort the imports"), UsefulTask("mimaReportBinaryIssues ", "Check binary issues"), UsefulTask("validatePullRequest ", "Validate pull request"), - UsefulTask("docs/paradox", "Build documentation (takes ~10+ minutes)"), - UsefulTask("docs/paradoxBrowse", "Browse the generated documentation (takes ~10+ minutes)"), + UsefulTask("docs/paradox", "Build documentation (license report will be generate on CI or Publish)"), + UsefulTask("docs/paradoxBrowse", + "Browse the generated documentation (license report will be generate on CI or Publish)"), UsefulTask("tips:", "prefix commands with `+` to run against cross Scala versions."), UsefulTask("Contributing guide:", "https://github.com/apache/incubator-pekko/blob/main/CONTRIBUTING.md")).map( _.noAlias)) diff --git a/project/ProjectIndexGenerator.scala b/project/ProjectIndexGenerator.scala new file mode 100644 index 0000000000..d727d49983 --- /dev/null +++ b/project/ProjectIndexGenerator.scala @@ -0,0 +1,75 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import sbt._ +import Keys._ + +object ProjectIndexGenerator extends AutoPlugin { + + object CliOptions { + val generateLicenseReportEnabled = CliOption("pekko.genlicensereport.enabled", false) + } + + override val projectSettings: Seq[Setting[_]] = inConfig(Compile)( + Seq( + resourceGenerators += + generateIndex(sourceDirectory, _ / "paradox" / "project" / "project-index.md"))) + + def generateIndex(dir: SettingKey[File], locate: File => File) = Def.task[Seq[File]] { + val file = locate(dir.value) + + val markdownFilesBeforeLicense = Seq( + "../common/binary-compatibility-rules.md", + "scala3.md", + "downstream-upgrade-strategy.md", + "../common/may-change.md", + "../additional/ide.md", + "immutable.md", + "../additional/osgi.md", + "migration-guides.md", + "rolling-update.md", + "issue-tracking.md", + "licenses.md") + val markdownFilesAfterLicense = Seq( + "../additional/faq.md", + "../additional/books.md", + "examples.md", + "links.md") + + val markdownFiles = if (CliOptions.generateLicenseReportEnabled.get) { + markdownFilesBeforeLicense ++ Seq("license-report.md") ++ markdownFilesAfterLicense + } else { + markdownFilesBeforeLicense ++ markdownFilesAfterLicense + } + + val content = + s""" + |# Project Information + | + |@@toc { depth=2 } + | + |@@@ index + | + |${markdownFiles.map(f => s"* [${f.replace(".md", "")}]($f)").mkString("\n")} + | + |@@@ + |""".stripMargin + + if (!file.exists || IO.read(file) != content) IO.write(file, content) + Seq(file) + } +}