Skip to content

Commit 384c074

Browse files
romanowskiromanowski
committed
Reformat reference, add section for scala command
1 parent f196f8d commit 384c074

File tree

8 files changed

+2541
-1684
lines changed

8 files changed

+2541
-1684
lines changed

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

Lines changed: 142 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ import scala.build.preprocessing.directives.{
1515
UsingDirectiveHandler
1616
}
1717
import scala.cli.ScalaCliCommands
18+
import scala.cli.commands.ScalaCommand
19+
import scala.cli.commands.RestrictedCommandsParser
1820

1921
object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
2022

@@ -81,10 +83,14 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
8183
private def cliOptionsContent(
8284
commands: Seq[Command[_]],
8385
allArgs: Seq[Arg],
84-
nameFormatter: Formatter[Name]
86+
nameFormatter: Formatter[Name],
87+
onlyRestricted: Boolean = false
8588
): String = {
89+
val argsToShow = if (!onlyRestricted) allArgs
90+
else
91+
allArgs.filterNot(RestrictedCommandsParser.isExperimentalOrRestricted)
8692

87-
val argsByOrigin = allArgs.groupBy(arg => cleanUpOrigin(arg.origin.getOrElse("")))
93+
val argsByOrigin = argsToShow.groupBy(arg => cleanUpOrigin(arg.origin.getOrElse("")))
8894

8995
val commandOrigins = for {
9096
command <- commands
@@ -97,78 +103,96 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
97103
(k, v.map(_._2).distinct.sortBy(_.name))
98104
}
99105

100-
val b = new StringBuilder
101-
102-
b.append(
103-
"""---
104-
|title: Command-line options
105-
|sidebar_position: 1
106-
|---
107-
|
108-
|This is a summary of options that are available for each subcommand of the `scala-cli` command.
109-
|
110-
|""".stripMargin
106+
val mainOptionsContent = new StringBuilder
107+
val hiddenOptionsContent = new StringBuilder
108+
109+
mainOptionsContent.append(
110+
s"""---
111+
|title: Command-line options
112+
|sidebar_position: 1
113+
|---
114+
|
115+
|${
116+
if (onlyRestricted)
117+
"**This document describes as scala-cli behaves if run as `scala` command. See more information in [SIP-46](https://github.com/scala/improvement-proposals/pull/46)**"
118+
else ""
119+
}
120+
|
121+
|This is a summary of options that are available for each subcommand of the `scala-cli` command.
122+
|
123+
|""".stripMargin
111124
)
112125

113126
for ((origin, originArgs) <- argsByOrigin.toVector.sortBy(_._1)) {
114-
val originArgs0 = originArgs.map(_.withOrigin(None)).distinct
115-
val originCommands = commandOriginsMap.getOrElse(origin, Nil)
116-
val formattedOrigin = formatOrigin(origin)
117-
val formattedCommands = originCommands.map { c =>
118-
// https://scala-cli.virtuslab.org/docs/reference/commands#install-completions
119-
val names = c.names.map(_.mkString(" "))
120-
val text = names.map("`" + _ + "`").mkString(" / ")
121-
s"[$text](./commands.md#${names.head.replace(" ", "-")})"
122-
}
123-
val availableIn = "Available in commands:\n" + formattedCommands.map("- " + _ + "\n").mkString
124-
b.append(
125-
s"""## $formattedOrigin options
126-
|
127-
|$availableIn
128-
|
129-
|<!-- Automatically generated, DO NOT EDIT MANUALLY -->
130-
|
131-
|""".stripMargin
132-
)
133-
134-
for (arg <- originArgs0.distinct) {
135-
import caseapp.core.util.NameOps._
136-
arg.name.option(nameFormatter)
137-
val aliases = arg.extraNames.map(_.option(nameFormatter))
127+
val distinctArgs = originArgs.map(_.withOrigin(None)).distinct
128+
val originCommands = commandOriginsMap.getOrElse(origin, Nil)
129+
val onlyForHiddenCommands = originCommands.nonEmpty && originCommands.forall(_.hidden)
130+
val allArgsHidden = distinctArgs.forall(_.noHelp)
131+
val isInternal = onlyForHiddenCommands || allArgsHidden
132+
val b = if (isInternal) hiddenOptionsContent else mainOptionsContent
133+
if (originCommands.nonEmpty) {
134+
val formattedOrigin = formatOrigin(origin)
135+
val formattedCommands = originCommands.map { c =>
136+
// https://scala-cli.virtuslab.org/docs/reference/commands#install-completions
137+
val names = c.names.map(_.mkString(" "))
138+
val text = names.map("`" + _ + "`").mkString(" , ")
139+
s"[$text](./commands.md#${names.head.replace(" ", "-")})"
140+
}
141+
val availableIn = "Available in commands:\n\n" + formattedCommands.mkString(", ")
142+
val header = if (isInternal) "###" else "##"
138143
b.append(
139-
s"""#### `${arg.name.option(nameFormatter)}`
144+
s"""$header $formattedOrigin options
145+
|
146+
|$availableIn
147+
|
148+
|<!-- Automatically generated, DO NOT EDIT MANUALLY -->
140149
|
141150
|""".stripMargin
142151
)
143-
if (aliases.nonEmpty)
144-
b.append(
145-
s"""Aliases: ${aliases.map("`" + _ + "`").mkString(", ")}
146-
|
147-
|""".stripMargin
148-
)
149-
for (desc <- arg.helpMessage.map(_.message))
150-
b.append(
151-
s"""$desc
152-
|
153-
|""".stripMargin
154-
)
152+
153+
for (arg <- distinctArgs) {
154+
import caseapp.core.util.NameOps._
155+
arg.name.option(nameFormatter)
156+
val names = (arg.name +: arg.extraNames).map(_.option(nameFormatter))
157+
b.append(s"### `${names.head}`\n\n")
158+
if (names.tail.nonEmpty)
159+
b.append(names.tail.map(n => s"`$n`").mkString("Aliases: ", ", ", "\n\n"))
160+
161+
if (isInternal || arg.noHelp) b.append("[Internal]\n")
162+
163+
for (desc <- arg.helpMessage.map(_.message))
164+
b.append(
165+
s"""$desc
166+
|
167+
|""".stripMargin
168+
)
169+
}
155170
}
156171
}
157172

158-
b.toString
173+
mainOptionsContent.append("## Internal options \n")
174+
mainOptionsContent.append(hiddenOptionsContent.toString)
175+
mainOptionsContent.toString
159176
}
160177

161-
private def commandsContent(commands: Seq[Command[_]]): String = {
178+
private def commandsContent(commands: Seq[Command[_]], onlyRestricted: Boolean): String = {
162179

163180
val b = new StringBuilder
164181

165182
b.append(
166-
"""---
167-
|title: Commands
168-
|sidebar_position: 3
169-
|---
170-
|
171-
|""".stripMargin
183+
s"""---
184+
|title: Commands
185+
|sidebar_position: 3
186+
|---
187+
|
188+
|${
189+
if (onlyRestricted)
190+
"**This document describes as scala-cli behaves if run as `scala` command. See more information in [SIP-46](https://github.com/scala/improvement-proposals/pull/46)**"
191+
else ""
192+
}
193+
|
194+
|
195+
|""".stripMargin
172196
)
173197

174198
val (hiddenCommands, mainCommands) = commands.partition(_.hidden)
@@ -179,19 +203,9 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
179203

180204
val headerPrefix = "#" * additionalIndentation
181205
val names = c.names.map(_.mkString(" "))
182-
b.append(
183-
s"""$headerPrefix## `${names.head}`
184-
|
185-
|""".stripMargin
186-
)
187-
if (names.lengthCompare(1) > 0) {
188-
b.append("Aliases:\n")
189-
for (n <- names.tail) {
190-
b.append(s"- `$n`")
191-
b.append("\n")
192-
}
193-
b.append("\n")
194-
}
206+
207+
b.append(s"$headerPrefix## ${names.head}\n\n")
208+
if (names.tail.nonEmpty) b.append(names.tail.mkString("Aliases: `", "`, `", "`\n\n"))
195209

196210
for (desc <- c.messages.helpMessage.map(_.message))
197211
b.append(
@@ -210,11 +224,9 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
210224
s"[$cleanedUp](./cli-options.md#$linkPart-options)"
211225
}
212226
b.append(
213-
"""Accepts options:
214-
|""".stripMargin
227+
s"""Accepts option groups: ${links.mkString(", ")}
228+
|""".stripMargin
215229
)
216-
for (link <- links)
217-
b.append(s"- $link\n")
218230
b.append("\n")
219231
}
220232
}
@@ -234,19 +246,26 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
234246

235247
private def usingContent(
236248
usingHandlers: Seq[UsingDirectiveHandler],
237-
requireHandlers: Seq[RequireDirectiveHandler]
249+
requireHandlers: Seq[RequireDirectiveHandler],
250+
onlyRestricted: Boolean
238251
): String = {
239252
val b = new StringBuilder
240253

241254
b.append(
242-
"""---
243-
|title: Directives
244-
|sidebar_position: 2
245-
|---
246-
|
247-
|## using directives
248-
|
249-
|""".stripMargin
255+
s"""---
256+
|title: Directives
257+
|sidebar_position: 2
258+
|---
259+
|
260+
|${
261+
if (onlyRestricted)
262+
"**This document describes as scala-cli behaves if run as `scala` command. See more information in [SIP-46](https://github.com/scala/improvement-proposals/pull/46)**"
263+
else ""
264+
}
265+
|
266+
|## using directives
267+
|
268+
|""".stripMargin
250269
)
251270

252271
def addHandlers(handlers: Seq[DirectiveHandler[_]]): Unit =
@@ -291,23 +310,40 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
291310

292311
def run(options: InternalDocOptions, args: RemainingArgs): Unit = {
293312

294-
val scalaCli = new ScalaCliCommands("scala-cli", isSipScala = false)
295-
val commands = scalaCli.commands
313+
val scalaCli = new ScalaCliCommands("scala-cli", isSipScala = false)
314+
val commands = scalaCli.commands
315+
val restrictedCommands =
316+
commands.iterator.collect { case s: ScalaCommand[_] if !s.isRestricted => s }.toSeq
296317
val allArgs = commands.flatMap(actualHelp(_).args)
297318
val nameFormatter = scalaCli.actualDefaultCommand.nameFormatter
298319

299-
val cliOptionsContent0 = cliOptionsContent(commands, allArgs, nameFormatter)
300-
val commandsContent0 = commandsContent(commands)
301-
val usingContent0 = usingContent(
320+
val allCliOptionsContent = cliOptionsContent(commands, allArgs, nameFormatter)
321+
val restrictedCliOptionsContent =
322+
cliOptionsContent(restrictedCommands, allArgs, nameFormatter, onlyRestricted = true)
323+
324+
val allCommandsContent = commandsContent(commands, onlyRestricted = false)
325+
val restrictedCommandsContent = commandsContent(restrictedCommands, onlyRestricted = true)
326+
327+
val allDirectivesContent = usingContent(
302328
ScalaPreprocessor.usingDirectiveHandlers,
303-
ScalaPreprocessor.requireDirectiveHandlers
329+
ScalaPreprocessor.requireDirectiveHandlers,
330+
onlyRestricted = false
331+
)
332+
val restrictedDirectivesContent = usingContent(
333+
ScalaPreprocessor.usingDirectiveHandlers.filterNot(_.isRestricted),
334+
ScalaPreprocessor.requireDirectiveHandlers.filterNot(_.isRestricted),
335+
onlyRestricted = true
304336
)
337+
val restrictedDocsDir = os.rel / "scala-command"
305338

306339
if (options.check) {
307340
val content = Seq(
308-
(os.rel / "cli-options.md") -> cliOptionsContent0,
309-
(os.rel / "commands.md") -> commandsContent0,
310-
(os.rel / "directives.md") -> usingContent0
341+
(os.rel / "cli-options.md") -> allCliOptionsContent,
342+
(os.rel / "commands.md") -> allCommandsContent,
343+
(os.rel / "directives.md") -> allDirectivesContent,
344+
(os.rel / restrictedDocsDir / "cli-options.md") -> restrictedCliOptionsContent,
345+
(os.rel / restrictedDocsDir / "commands.md") -> restrictedCommandsContent,
346+
(os.rel / restrictedDocsDir / "directives.md") -> restrictedDirectivesContent
311347
)
312348
var anyDiff = false
313349
for ((dest, content0) <- content) {
@@ -328,9 +364,19 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
328364
sys.exit(1)
329365
}
330366
else {
331-
maybeWrite(options.outputPath / "cli-options.md", cliOptionsContent0)
332-
maybeWrite(options.outputPath / "commands.md", commandsContent0)
333-
maybeWrite(options.outputPath / "directives.md", usingContent0)
367+
maybeWrite(options.outputPath / "cli-options.md", allCliOptionsContent)
368+
maybeWrite(options.outputPath / "commands.md", allCommandsContent)
369+
maybeWrite(options.outputPath / "directives.md", allDirectivesContent)
370+
371+
maybeWrite(
372+
options.outputPath / restrictedDocsDir / "cli-options.md",
373+
restrictedCliOptionsContent
374+
)
375+
maybeWrite(options.outputPath / restrictedDocsDir / "commands.md", restrictedCommandsContent)
376+
maybeWrite(
377+
options.outputPath / restrictedDocsDir / "directives.md",
378+
restrictedDirectivesContent
379+
)
334380
}
335381
}
336382
}

0 commit comments

Comments
 (0)