Skip to content

Commit dc44fe2

Browse files
GedochaoGedochao
authored
Merge pull request #4007 from Gedochao/docs/tweak-website-warnings
Solve docs' website warnings
2 parents 4832457 + e76ebfc commit dc44fe2

12 files changed

Lines changed: 3042 additions & 3183 deletions

File tree

‎modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala‎

Lines changed: 44 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,9 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
144144
(k, v.map(_._2).distinct.sortBy(_.name))
145145
}
146146

147+
// Collect all origins that are referenced by commands, even if they have no args
148+
val allReferencedOrigins = commandOriginsMap.keySet ++ argsByOrigin.keySet
149+
147150
val mainOptionsContent = new StringBuilder
148151
val hiddenOptionsContent = new StringBuilder
149152

@@ -167,13 +170,15 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
167170

168171
mainOptionsContent.section(scalacOptionForwarding)
169172

170-
for ((origin, originArgs) <- argsByOrigin.toVector.sortBy(_._1)) {
173+
for (origin <- allReferencedOrigins.toVector.sortBy(identity)) {
174+
val originArgs = argsByOrigin.getOrElse(origin, Nil)
171175
val distinctArgs = originArgs.map(_.withOrigin(None)).distinct
172176
val originCommands = commandOriginsMap.getOrElse(origin, Nil)
173177
val onlyForHiddenCommands = originCommands.nonEmpty && originCommands.forall(_.hidden)
174-
val allArgsHidden = distinctArgs.forall(_.noHelp)
175-
val isInternal = onlyForHiddenCommands || allArgsHidden
176-
val b = if (isInternal) hiddenOptionsContent else mainOptionsContent
178+
// Empty option groups should not be treated as internal if they're referenced by commands
179+
val allArgsHidden = distinctArgs.nonEmpty && distinctArgs.forall(_.noHelp)
180+
val isInternal = onlyForHiddenCommands || allArgsHidden
181+
val b = if (isInternal) hiddenOptionsContent else mainOptionsContent
177182
if (originCommands.nonEmpty) {
178183
val formattedOrigin = formatOrigin(origin)
179184
val formattedCommands = originCommands.map { c =>
@@ -194,35 +199,41 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
194199
|""".stripMargin
195200
)
196201

197-
for (arg <- distinctArgs) {
198-
import caseapp.core.util.NameOps._
199-
arg.name.option(nameFormatter)
200-
val names = (arg.name +: arg.extraNames).map(_.option(nameFormatter))
201-
b.append(s"### `${names.head}`\n\n")
202-
if (names.tail.nonEmpty)
203-
b.append(
204-
names
205-
.tail
206-
.sortBy(_.dropWhile(_ == '-'))
207-
.map {
208-
case name if arg.deprecatedOptionAliases.contains(name) =>
209-
s"[deprecated] `$name`"
210-
case name => s"`$name`"
211-
}
212-
.mkString("Aliases: ", ", ", "\n\n")
213-
)
214-
215-
if (onlyRestricted)
216-
b.section(s"`${arg.level.md}` per Scala Runner specification")
217-
else if (isInternal || arg.noHelp) b.append("[Internal]\n")
218-
219-
for (desc <- arg.helpMessage.map(_.referenceDocMessage))
220-
b.append(
221-
s"""$desc
222-
|
223-
|""".stripMargin
224-
)
225-
}
202+
if (distinctArgs.nonEmpty)
203+
for (arg <- distinctArgs) {
204+
import caseapp.core.util.NameOps._
205+
arg.name.option(nameFormatter)
206+
val names = (arg.name +: arg.extraNames).map(_.option(nameFormatter))
207+
b.append(s"### `${names.head}`\n\n")
208+
if (names.tail.nonEmpty)
209+
b.append(
210+
names
211+
.tail
212+
.sortBy(_.dropWhile(_ == '-'))
213+
.map {
214+
case name if arg.deprecatedOptionAliases.contains(name) =>
215+
s"[deprecated] `$name`"
216+
case name => s"`$name`"
217+
}
218+
.mkString("Aliases: ", ", ", "\n\n")
219+
)
220+
221+
if (onlyRestricted)
222+
b.section(s"`${arg.level.md}` per Scala Runner specification")
223+
else if (isInternal || arg.noHelp) b.append("[Internal]\n")
224+
225+
for (desc <- arg.helpMessage.map(_.referenceDocMessage))
226+
b.append(
227+
s"""$desc
228+
|
229+
|""".stripMargin
230+
)
231+
}
232+
else
233+
// Empty option group - add a note
234+
b.append(
235+
"*This section was automatically generated and may be empty if no options were available.*\n\n"
236+
)
226237
}
227238
}
228239

‎website/docs/commands/publishing/publish.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ or relative (beware of name clashes with pre-defined repositories above).
285285
### Authentication
286286

287287
Specify publish repository authentication either on the command-line or via
288-
using directives. See user / password / realm in the [settings table](#settings)
288+
using directives. See user / password / realm in the [settings table](#other-settings)
289289
and the [CI overrides](#ci-overrides).
290290

291291
### Connection parameters configuration

‎website/docs/reference/scala-command/cli-options.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,16 @@ are assumed to be Scala compiler options and will be propagated to Scala Compile
4242

4343

4444

45+
## Benchmarking options
46+
47+
Available in commands:
48+
49+
[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
50+
51+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
52+
53+
*This section was automatically generated and may be empty if no options were available.*
54+
4555
## Compilation server options
4656

4757
Available in commands:
@@ -186,6 +196,16 @@ Aliases: `-f`
186196

187197
Force overwriting values for key
188198

199+
## Cross options
200+
201+
Available in commands:
202+
203+
[`compile`](./commands.md#compile), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
204+
205+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
206+
207+
*This section was automatically generated and may be empty if no options were available.*
208+
189209
## Debug options
190210

191211
Available in commands:
@@ -664,6 +684,26 @@ Aliases: `--list-main-class`, `--list-main-classes`, `--list-main-method`, `--li
664684

665685
List main classes available in the current context
666686

687+
## Markdown options
688+
689+
Available in commands:
690+
691+
[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
692+
693+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
694+
695+
*This section was automatically generated and may be empty if no options were available.*
696+
697+
## Pgp scala signing options
698+
699+
Available in commands:
700+
701+
[`config`](./commands.md#config)
702+
703+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
704+
705+
*This section was automatically generated and may be empty if no options were available.*
706+
667707
## Power options
668708

669709
Available in commands:
@@ -678,6 +718,16 @@ Available in commands:
678718

679719
Allows to use restricted & experimental features
680720

721+
## Python options
722+
723+
Available in commands:
724+
725+
[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
726+
727+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
728+
729+
*This section was automatically generated and may be empty if no options were available.*
730+
681731
## Run options
682732

683733
Available in commands:
@@ -1160,6 +1210,16 @@ Allows to execute a passed string as Java code
11601210

11611211
A synonym to --scala-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
11621212

1213+
## Source generator options
1214+
1215+
Available in commands:
1216+
1217+
[`bsp`](./commands.md#bsp), [`compile`](./commands.md#compile), [`doc`](./commands.md#doc), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test)
1218+
1219+
<!-- Automatically generated, DO NOT EDIT MANUALLY -->
1220+
1221+
*This section was automatically generated and may be empty if no options were available.*
1222+
11631223
## Suppress warning options
11641224

11651225
Available in commands:

‎website/docusaurus.config.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ module.exports = {
99
url: 'https://scala-cli.virtuslab.org/',
1010
baseUrl: '/',
1111
onBrokenLinks: 'throw',
12+
onBrokenAnchors: 'throw',
1213
markdown: {
1314
hooks: {
14-
onBrokenMarkdownLinks: 'warn'
15+
onBrokenMarkdownLinks: 'throw'
1516
}
1617
},
1718
favicon: 'img/favicon.ico',
@@ -39,7 +40,7 @@ module.exports = {
3940
{
4041
// type: 'doc',
4142
label: "Use cases",
42-
to: '/#use_cases',
43+
to: '/',
4344
items: [
4445
{
4546
to: '/education',

‎website/package.json‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,28 @@
1414
"write-heading-ids": "docusaurus write-heading-ids"
1515
},
1616
"dependencies": {
17+
"@algolia/client-search": "^5.46.0",
1718
"@docusaurus/core": "^3.9.2",
19+
"@docusaurus/plugin-content-docs": "^3.9.2",
1820
"@docusaurus/preset-classic": "^3.9.2",
21+
"@docusaurus/theme-common": "^3.9.2",
1922
"@easyops-cn/docusaurus-search-local": "^0.52.2",
2023
"@mdx-js/react": "^3.1.1",
24+
"@types/react": "^19.2.7",
2125
"clsx": "^2.1.1",
2226
"docusaurus-plugin-sass": "^0.2.6",
2327
"react": "^19.2.1",
2428
"react-dom": "^19.2.1",
29+
"react-loadable": "^5.5.0",
2530
"react-player": "^2.16.1",
26-
"sass": "^1.95.0"
31+
"sass": "^1.96.0",
32+
"search-insights": "^2.17.3"
33+
},
34+
"resolutions": {
35+
"react-loadable": "^5.5.0",
36+
"search-insights": "^2.17.3",
37+
"@algolia/client-search": "^5.46.0",
38+
"@types/react": "^19.2.7"
2739
},
2840
"browserslist": {
2941
"production": [

‎website/src/pages/install.js‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import React from 'react';
22
import Layout from '@theme/Layout';
3+
import Heading from '@theme/Heading';
34

45
import Section from "../components/Section"
56
import BigHeader from "../components/BigHeader"
@@ -12,7 +13,6 @@ const Index = (props) => {
1213

1314
<div className="container content">
1415

15-
1616
{/* Install Scala CLI */}
1717
<Section className="section-install-cli">
1818
<div className="row">
@@ -30,7 +30,10 @@ const Index = (props) => {
3030

3131

3232
<Section className="section-about advanced-install">
33-
33+
{/* Anchor targets for deep linking - using Heading so Docusaurus can detect them */}
34+
<Heading as="h2" id="advanced-installation" style={{display: 'none', margin: 0, padding: 0}}>Advanced Installation</Heading>
35+
<Heading as="h2" id="scala-js" style={{display: 'none', margin: 0, padding: 0}}>Scala.js</Heading>
36+
<Heading as="h2" id="scala-native" style={{display: 'none', margin: 0, padding: 0}}>Scala Native</Heading>
3437
<AdvancedInstallation/>
3538

3639
</Section>

‎website/src/scss/_variables.scss‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
$theme-red: #F23135;
2+
$theme-yellow: #FFD583;
3+

‎website/src/scss/components/section-install-cli.scss‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@use '../variables' as *;
2+
13
.section-install-cli {
24
margin-top: 130px;
35
margin-bottom: 130px;

‎website/src/scss/components/section-use-tiles.scss‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@use '../variables' as *;
2+
13
.section-use-tiles {
24
margin-top: 130px;
35
margin-bottom: 130px;

‎website/src/scss/components/section-yellow-banner.scss‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@use '../variables' as *;
2+
13
.section-yellow-banner {
24
margin-top: 50px;
35
margin-bottom: 130px;

0 commit comments

Comments
 (0)