Update documentation for hugo/diagrams relocation to riddl-gen

respencer-ncl · claude · respencer-ncl · commit cf4e9683f827 · 2026-01-28T22:29:18.000-05:00
- Update command-line-help.md with current riddlc commands
- Add riddl-gen notices to hugo.md, diagrams.md, translation/_index.md
- Update options.md with current command options (bastify, unbastify, etc.)
- Update ways-to-use-riddl.md with riddl-gen reference
- Add deprecation warning to riddlcExamples.md

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/doc/src/main/hugo/content/future-work/diagrams.md b/doc/src/main/hugo/content/future-work/diagrams.md
@@ -1,7 +1,24 @@
 ---
 title: "Diagrams"
-description: "RIDDL can generate diagrams"
+description: "RIDDL diagram generation"
 type: "page"
 draft: "false"
 weight: 20
 ---
+
+{{% hint info %}}
+**Moved to riddl-gen**
+
+Diagram generation has been moved to the
+[riddl-gen](https://github.com/ossuminc/riddl-gen) repository.
+
+The `riddl-gen` tool can generate various diagram types from RIDDL models:
+- Context maps
+- Data flow diagrams
+- Entity relationship diagrams
+- Use case diagrams
+- And more
+
+Please see the [riddl-gen documentation](https://github.com/ossuminc/riddl-gen)
+for usage instructions.
+{{% /hint %}}
diff --git a/doc/src/main/hugo/content/guides/authors/riddlcExamples.md b/doc/src/main/hugo/content/guides/authors/riddlcExamples.md
@@ -5,6 +5,12 @@ draft: true
 weight: 20
 ---
 
+{{% hint warning %}}
+**Note**: This page references the `hugo` and `hugo-git-check` commands which
+have been moved to the [riddl-gen](https://github.com/ossuminc/riddl-gen)
+repository. The examples below need to be updated for current `riddlc` commands.
+{{% /hint %}}
+
 Because riddlc is a very rich command, we thought it might be useful to provide
 some examples. We use these commands in our day to day work and hope that these
 examples give you ideas on how to adapt riddlc to your particular work style
diff --git a/doc/src/main/hugo/content/guides/implementors/ways-to-use-riddl.md b/doc/src/main/hugo/content/guides/implementors/ways-to-use-riddl.md
@@ -53,9 +53,10 @@ command in sbt. Follow these steps:
     * `riddlcPath := file("...")` This defaults to "riddlc" which is 
       appropriate if the right version is in your path; otherwise specify the
       full path to the `riddlc` command
-    * `riddlcOptions := Seq("from", "path/to/config/file", "hugo")` This is 
-      just an example, you can put any command or options you want in that 
-      sequence. Use `riddlc help` to find out what commands you can use. 
+    * `riddlcOptions := Seq("from", "path/to/config/file", "validate")` This is
+      just an example, you can put any command or options you want in that
+      sequence. Use `riddlc help` to find out what commands you can use.
+      Note: Hugo generation has moved to the `riddl-gen` repository. 
 * To run a translator in this way, put a `riddlc.conf` file next to the top 
   level `.riddl` file you want to translate. The content of that file can 
   specify common options and the commands you want to support from 
@@ -64,7 +65,7 @@ command in sbt. Follow these steps:
   These files use 
   [Human-Oriented-CONfiguration](https://github.com/lightbend/config)
 
-```hocon 
+```hocon
 common {
     show-times = true
     verbose = true
@@ -74,20 +75,18 @@ common {
     show-missing-warnings = false
     show-style-warnings = false
 }
-hugo {
+validate {
     input-file = "ReactiveBBQ.riddl"
-    output-dir = "target/hugo/ReactiveBBQ"
-    project-name = "Reactive BBQ"
-    site-title = "Reactive BBQ Generated Specification"
-    site-description = "This site provides a specification for the Reactive BBQ application as generated by riddlc"
-    site-logo-path = "images/RBBQ.png"
-    erase-output = true
-    base-url = "https://bbq.riddl.tech"
-    source-url = "https://github.com/ossuminc/riddl"
-    edit-path = "/-/blob/main/src/riddl/ReactiveBBQ"
 }
-validate {
+prettify {
     input-file = "ReactiveBBQ.riddl"
+    output-dir = "target/prettified"
+}
 ```
 
+{{% hint info %}}
+**Note**: Hugo documentation generation has moved to the
+[riddl-gen](https://github.com/ossuminc/riddl-gen) repository.
+{{% /hint %}}
+
 
diff --git a/doc/src/main/hugo/content/tooling/riddlc/command-line-help.md b/doc/src/main/hugo/content/tooling/riddlc/command-line-help.md
@@ -6,8 +6,8 @@ draft: false
 weight: 10
 ---
 
-riddlc is the command that makes all the magic happen. As you will see, riddlc 
-is a rich and powerful tool for processing RIDDL input. 
+riddlc is the command that makes all the magic happen. As you will see, riddlc
+is a rich and powerful tool for processing RIDDL input.
 
 ## Command Syntax overview
 `riddlc` uses a sub-command structure. At a high level, the command line syntax
@@ -16,125 +16,129 @@ is very simple:
 > riddlc [common options] command-name [command-options]
 ```
 
+## Available Commands
+
+The following commands are available in `riddlc`:
+
+| Command | Description |
+|---------|-------------|
+| `about` | Print out information about RIDDL |
+| `bastify` | Convert a RIDDL file to BAST (Binary AST) format |
+| `dump` | Dump the AST of the input file |
+| `unbastify` | Convert a BAST file back to RIDDL source files |
+| `flatten` | Flatten all includes into a single file |
+| `from` | Load a configuration file and execute a command from it |
+| `help` | Print out how to use this program |
+| `info` | Print out build information about this program |
+| `onchange` | Watch a directory and run a command when changes occur |
+| `parse` | Parse the input file and report any errors |
+| `prettify` | Reformat RIDDL source to a standard layout |
+| `repeat` | Repeatedly run a command for edit-build-check cycles |
+| `stats` | Generate statistics about a RIDDL model |
+| `validate` | Parse and validate the input file |
+| `version` | Print the version of riddlc and exit |
+
+{{% hint info %}}
+**Note**: Hugo documentation generation and diagram generation have been moved
+to the [riddl-gen](https://github.com/ossuminc/riddl-gen) repository. Use that
+tool if you need to generate Hugo sites or diagrams from RIDDL models.
+{{% /hint %}}
+
 ## Info Command Output
 For this version of `riddlc`:
 ```shell
-> content % riddlc info
+> riddlc info
 [info] About riddlc:
 [info]            name: riddlc
-[info]         version: 0.14.0
+[info]         version: 1.1.2
 [info]   documentation: https://riddl.tech
-[info]       copyright: © 2019-2022 Ossum Inc.
-[info]        built at: 2022-09-09 11:28:07.485-0400
+[info]       copyright: © 2019-2026 Ossum Inc.
 [info]        licenses: Apache License, Version 2.0
 [info]    organization: Ossum Inc.
-[info]   scala version: 2.13.8
-[info]     sbt version: 1.7.1
-```
-the help text shows the commands and options available:
-
+[info]   scala version: 3.3.7
 ```
-RIDDL Compiler © 2019-2022 Ossum Inc. All rights reserved."
-Version: 0.13.3-2-49ff0a59-20220909-1104-SNAPSHOT
 
-This program parses, validates and translates RIDDL sources to other kinds
-of documents. RIDDL is a language for system specification based on Domain
-Drive Design, Reactive Architecture, and distributed system principles.
+## Common Options
 
+The following options apply to all commands:
 
-Usage: riddlc [options]
-
+```
   -t | --show-times
-        Show compilation phase execution times 
+        Show parsing phase execution times
+  -I | --show-include-times
+        Show parsing of included files execution times
   -d | --dry-run
         go through the motions but don't write any changes
   -v | --verbose
-        Provide verbose output detailing riddlc's actions
+        Provide verbose output detailing actions taken by riddlc
   -D | --debug
         Enable debug output. Only useful for riddlc developers
   -q | --quiet
         Do not print out any output, just do the requested command
-  -w | --suppress-warnings
+  -a | --no-ansi-messages
+        Do not print messages with ANSI formatting
+  -w <value> | --show-warnings <value>
         Suppress all warning messages so only errors are shown
-  -m | --suppress-missing-warnings
-        Show warnings about things that are missing
-  -s | --suppress-style-warnings
-        Show warnings about questionable input style. 
-  -P <value> | --plugins-dir <value>
-        Load riddlc command extension plugins from this directory.
-
-Usage:  [about|dump|from|help|hugo|info|parse|repeat|validate|version] <args>...
-
-Command: about
-  Print out information about RIDDL
-
-Command: dump input-file
-    input-file
-
-Command: from config-file target-command
-  Loads a configuration file and executes the command in it
-    config-file
-          A HOCON configuration file with riddlc options in it.
-    target-command
-          The name of the command to select from the configuration file
-
-Command: help
-  Print out how to use this program
-
-Command: hugo [options] input-file
-  Parse and validate the input-file and then translate it into the input
-  needed for hugo to translate it to a functioning web site.
-    input-file
-          required riddl input file to read
-    -o <value> | --output-dir <value>
-          required output directory for the generated output
-    -p <value> | --project-name <value>
-          optional project name to associate with the generated output
-    -e <value> | --erase-output <value>
-          Erase entire output directory before putting out files
-    -b <value> | --base-url <value>
-          Optional base URL for root of generated http URLs
-    -t <value> | --themes <value>
-          Add theme name/url pairs to use alternative Hugo themes
-    -s <value> | --source-url <value>
-          URL to the input file's Git Repository
-    -h <value> | --edit-path <value>
-          Path to add to source-url to allow editing
-    -m <value> | --site-logo-path <value>
-          Path, in 'static' directory to placement and use
-          of the site logo.
-    -n <value> | --site-logo-url <value>
-          URL from which to copy the site logo.
-
-Command: info
-  Print out build information about this program
-
-Command: parse input-file
-    input-file
-
-Command: repeat [options] config-file target-command [refresh-rate] [max-cycles]
-  This command supports the edit-build-check cycle. It doesn't end
-  until <max-cycles> has completed or EOF is reached on standard
-  input. During that time, the selected subcommands are repeated.
-    config-file
-          The path to the configuration file that should be repeated
-    target-command
-          The name of the command to select from the configuration file
-    refresh-rate
-          Specifies the rate at which the <git-clone-dir> is checked
-  for updates so the process to regenerate the hugo site is
-  started
-    max-cycles
-          Limit the number of check cycles that will be repeated.
-    -n | --interactive
-          This option causes the repeat command to read from the standard
-          input and when it reaches EOF (Ctrl-D is entered) then it cancels
-          the loop to exit.
-
-Command: validate input-file
-    input-file
-
-Command: version
-  Print the version of riddlc and exits
+  -m <value> | --show-missing-warnings <value>
+        Suppress warnings about things that are missing
+  -s <value> | --show-style-warnings <value>
+        Suppress warnings about questionable input style
+  -u <value> | --show-usage-warnings <value>
+        Suppress warnings about usage of definitions
+  -i <value> | --show-info-messages <value>
+        Suppress information output
+  -S <value> | --sort-messages-by-location <value>
+        Print all messages sorted by file name and line number
+  -G <value> | --group-messages-by-kind <value>
+        Print all messages grouped by severity
+  -x <value> | --max-parallel-parsing <value>
+        Maximum number of include files parsed in parallel
+  --max-include-wait <value>
+        Maximum time to wait for include file parsing
+  --warnings-are-fatal <value>
+        Makes validation warnings fatal
+  -B | --auto-generate-bast
+        Automatically generate .bast files after parsing
+```
+
+## Command Details
+
+### bastify
+Convert a RIDDL file to BAST (Binary AST) format for faster loading:
+```shell
+riddlc bastify input-file.riddl
+```
+Creates a `.bast` file next to the input file.
+
+### unbastify
+Convert a BAST file back to RIDDL source:
+```shell
+riddlc unbastify input-file.bast -o output-dir
+```
+
+### from
+Load options from a HOCON configuration file:
+```shell
+riddlc from config-file.conf target-command
+```
 
+### prettify
+Reformat RIDDL source to a standard layout:
+```shell
+riddlc prettify input-file.riddl -o output-dir
 ```
+Options:
+- `--project-name <value>` - Project name for the output
+- `-s | --single-file <value>` - Resolve all includes into a single file
+
+### validate
+Parse and validate a RIDDL file:
+```shell
+riddlc validate input-file.riddl
+```
+
+### stats
+Generate statistics about a RIDDL model:
+```shell
+riddlc stats -I input-file.riddl
+```
diff --git a/doc/src/main/hugo/content/tooling/riddlc/translation/_index.md b/doc/src/main/hugo/content/tooling/riddlc/translation/_index.md
@@ -6,19 +6,29 @@ draft: "false"
 weight: 50
 ---
 
-The RIDDL compiler, `riddlc` is able to translate RIDDL into a variety of other
-document types, after the input passes the 
-[compilation phases]({{< relref "../compilation.md" >}}).  
+{{% hint warning %}}
+**Moved to riddl-gen**
 
-The various kinds of output from `riddlc` are described in the following 
-sections:
+The RIDDL translation commands (Hugo documentation generation and diagram
+generation) have been moved to the
+[riddl-gen](https://github.com/ossuminc/riddl-gen) repository.
 
-* [_Hugo_]({{< relref "hugo.md" >}}) - Hugo source input for producing an 
-  HTML website where diagrams are all automatically deduced from the RIDDL 
-  model
+Please use `riddl-gen` for:
+- Generating Hugo-based documentation websites from RIDDL models
+- Generating various diagram types (context maps, data flow diagrams, etc.)
 
-{{% hint ok %}}
-It is recommended that you become familiar with the `riddlc`command line and 
-configuration [options]({{< relref "options" >}}) as these control the kind of 
-output generated.
+The core `riddlc` compiler focuses on parsing, validation, and BAST
+serialization.
 {{% /hint %}}
+
+## What riddlc Can Do
+
+The `riddlc` compiler provides these core capabilities:
+
+- **Parse** - Parse RIDDL source files and report syntax errors
+- **Validate** - Validate RIDDL models for semantic correctness
+- **Prettify** - Reformat RIDDL source to a standard layout
+- **BAST** - Convert between RIDDL and Binary AST format for faster loading
+- **Stats** - Generate statistics about RIDDL models
+
+See the [command-line help]({{< relref "command-line-help.md" >}}) for details.
diff --git a/doc/src/main/hugo/content/tooling/riddlc/translation/hugo.md b/doc/src/main/hugo/content/tooling/riddlc/translation/hugo.md
diff --git a/doc/src/main/hugo/content/tooling/riddlc/translation/options.md b/doc/src/main/hugo/content/tooling/riddlc/translation/options.md
