Restore auto generation of compiler option table (#6373)

IntersectMBO · Aug 2, 2024 · d3cf117 · d3cf117
1 parent 88c7e23
commit d3cf117
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 53 deletions.
diff --git a/.gitignore b/.gitignore
@@ -75,6 +75,9 @@ pkgs/.stack
 *.code-workspace
 .*.sw*
 
+# Doc site
+yarn.lock
+
 # Misc
 act-event.json
 .history/
@@ -109,4 +112,3 @@ plutus-pab/test-node/alonzo-purple/db
 *.timelog
 *.stacks
 .nvimrc
-
diff --git a/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md b/doc/docusaurus/docs/reference/plutus-tx-compiler-options.md
@@ -2,6 +2,11 @@
 sidebar_position: 5
 ---
 
+<!---
+This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc.
+Do NOT modify by hand.
+--->
+
 # Plutus Tx compiler options
 
 These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for instance
@@ -13,33 +18,34 @@ These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for in
 
 For each boolean option, you can add a `no-` prefix to switch it off, such as `no-typecheck`, `no-simplifier-beta`.
 
-| Option                           | Value Type    | Default | Description |
-|----------------------------------|---------------|---------|-------------|
-| `conservative-optimisation`      | Bool          | False   | When conservative optimisation is used, only the optimisations that never make the program worse (in terms of cost or size) are employed. Implies `no-relaxed-float-in`.  |
-| `context-level`                  | Int           | 1       | Set context level for error messages. |
-| `coverage-all`                   | Bool          | False   | Add all available coverage annotations in the trace output |
-| `coverage-boolean`               | Bool          | False   | Add boolean coverage annotations in the trace output |
-| `coverage-location`              | Bool          | False   | Add location coverage annotations in the trace output |
-| `defer-errors`                   | Bool          | False   | If a compilation error happens and this option is turned on, the compilation error is suppressed and the original Haskell expression is replaced with a runtime-error expression. |
-| `dump-compilation-trace`         | Bool          | False   | Dump compilation trace for debugging |
-| `dump-pir`                       | Bool          | False   | Dump Plutus IR |
-| `dump-plc`                       | Bool          | False   | Dump Typed Plutus Core |
-| `dump-uplc`                      | Bool          | False   | Dump Untyped Plutus Core |
-| `max-cse-iterations`             | Int           | 4       | Set the max iterations for CSE |
-| `max-simplifier-iterations-pir`  | Int           | 12      | Set the max iterations for the PIR simplifier |
-| `max-simplifier-iterations-uplc` | Int           | 12      | Set the max iterations for the UPLC simplifier |
-| `optimize`                       | Bool          | True    | Run optimization passes such as simplification and floating let-bindings. |
-| `pedantic`                       | Bool          | False   | Run type checker after each compilation pass |
-| `profile-all`                    | ProfileOpts   | None    | Set profiling options to All, which adds tracing when entering and exiting a term. |
-| `relaxed-float-in`               | Bool          | True    | Use a more aggressive float-in pass, which often leads to reduced costs but may occasionally lead to slightly increased costs. |
-| `remove-trace`                   | Bool          | False   | Eliminate calls to `trace` from Plutus Core |
-| `simplifier-beta`                | Bool          | True    | Run a simplification pass that performs beta transformations |
-| `simplifier-inline`              | Bool          | True    | Run a simplification pass that performs inlining |
-| `simplifier-remove-dead-bindings`| Bool          | True    | Run a simplification pass that removes dead bindings |
-| `simplifier-unwrap-cancel`       | Bool          | True    | Run a simplification pass that cancels unwrap/wrap pairs |
-| `strictify-bindings`             | Bool          | True    | Run a simplification pass that makes bindings stricter |
-| `target-version`                 | Version       | 1.1.0   | The target Plutus Core language version |
-| `typecheck`                      | Bool          | True    | Perform type checking during compilation. |
-| `verbosity`                      | Verbosity     | Quiet   | Set logging verbosity level (0=Quiet, 1=Verbose, 2=Debug) |
-
+|Option|Value Type|Default|Description|
+|-|-|-|-|
+|`conservative-optimisation`|Bool|False|When conservative optimisation is used, only the optimisations that never make the program worse (in terms of cost or size) are employed. Implies `no-relaxed-float-in`, `no-inline-constants`, and `preserve-logging`.|
+|`context-level`|Int|1|Set context level for error messages.|
+|`coverage-all`|Bool|False|Add all available coverage annotations in the trace output|
+|`coverage-boolean`|Bool|False|Add boolean coverage annotations in the trace output|
+|`coverage-location`|Bool|False|Add location coverage annotations in the trace output|
+|`defer-errors`|Bool|False|If a compilation error happens and this option is turned on, the compilation error is suppressed and the original Haskell expression is replaced with a runtime-error expression.|
+|`dump-compilation-trace`|Bool|False|Dump compilation trace for debugging|
+|`dump-pir`|Bool|False|Dump Plutus IR|
+|`dump-tplc`|Bool|False|Dump Typed Plutus Core|
+|`dump-uplc`|Bool|False|Dump Untyped Plutus Core|
+|`inline-constants`|Bool|True|Always inline constants. Inlining constants always reduces script costs slightly, but may increase script sizes if a large constant is used more than once. Implied by `no-conservative-optimisation`.|
+|`max-cse-iterations`|Int|4|Set the max iterations for CSE|
+|`max-simplifier-iterations-pir`|Int|12|Set the max iterations for the PIR simplifier|
+|`max-simplifier-iterations-uplc`|Int|12|Set the max iterations for the UPLC simplifier|
+|`optimize`|Bool|True|Run optimization passes such as simplification and floating let-bindings.|
+|`pedantic`|Bool|False|Run type checker after each compilation pass|
+|`preserve-logging`|Bool|False|Turn off optimisations that may alter (i.e., add, remove or change the order of) trace messages. Implied by `conservative-optimisation`.|
+|`profile-all`|ProfileOpts|None|Set profiling options to All, which adds tracing when entering and exiting a term.|
+|`relaxed-float-in`|Bool|True|Use a more aggressive float-in pass, which often leads to reduced costs but may occasionally lead to slightly increased costs. Implied by `no-conservative-optimisation`.|
+|`remove-trace`|Bool|False|Eliminate calls to `trace` from Plutus Core|
+|`simplifier-beta`|Bool|True|Run a simplification pass that performs beta transformations|
+|`simplifier-inline`|Bool|True|Run a simplification pass that performs inlining|
+|`simplifier-remove-dead-bindings`|Bool|True|Run a simplification pass that removes dead bindings|
+|`simplifier-unwrap-cancel`|Bool|True|Run a simplification pass that cancels unwrap/wrap pairs|
+|`strictify-bindings`|Bool|True|Run a simplification pass that makes bindings stricter|
+|`target-version`|Version|1.1.0|The target Plutus Core language version|
+|`typecheck`|Bool|True|Perform type checking during compilation.|
+|`verbosity`|Verbosity|Quiet|Set logging verbosity level (0=Quiet, 1=Verbose, 2=Debug)|
 
diff --git a/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs b/plutus-tx-plugin/app/GeneratePluginOptionsDoc.hs
@@ -1,3 +1,4 @@
+-- editorconfig-checker-disable-file
 {-# LANGUAGE ApplicativeDo     #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE QuasiQuotes       #-}
@@ -40,29 +41,34 @@ main = do
     Text.writeFile (Text.unpack $ paramOutputFile params) optionsTable
 
 optionsTable :: Text
-optionsTable = [fmt|
-..
-   This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc.
-   Do not modify by hand.
+optionsTable = Text.stripStart $ [fmt|
+---
+sidebar_position: 5
+---
 
-.. list-table::
-   :header-rows: 1
-   :widths: 35 15 15 50
+<!---
+This file is generated by running plutus-tx-plugin:gen-plugin-opts-doc.
+Do NOT modify by hand.
+--->
 
-   * - Option
-     - Value Type
-     - Default
-     - Description
+# Plutus Tx compiler options
 
+These options can be passed to the compiler via the `OPTIONS_GHC` pragma, for instance
+
+``` haskell
+{{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:dump-uplc #-}}
+{{-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:max-simplifier-iterations-uplc=3 #-}}
+```
+
+For each boolean option, you can add a `no-` prefix to switch it off, such as `no-typecheck`, `no-simplifier-beta`.
+
+|Option|Value Type|Default|Description|
+|-|-|-|-|
 {Text.unlines $ uncurry genRow <$> Map.toList O.pluginOptions}
 |]
 
 genRow :: O.OptionKey -> O.PluginOption -> Text
-genRow k (O.PluginOption tr _ field desc _) = [fmt|
-   * - ``{k}``
-     - {show tr}
-     - {show (pretty defaultValue)}
-     - {desc}
-|]
+genRow k (O.PluginOption tr _ field desc _) =
+  [fmt||`{k}`|{show tr}|{show (pretty defaultValue)}|{desc}||]
     where
         defaultValue = O.defaultPluginOptions ^. field
diff --git a/plutus-tx-plugin/src/PlutusTx/Options.hs b/plutus-tx-plugin/src/PlutusTx/Options.hs
@@ -152,8 +152,8 @@ pluginOptions =
               desc =
                 "When conservative optimisation is used, only the optimisations that \
                 \never make the program worse (in terms of cost or size) are employed. \
-                \Implies ``no-relaxed-float-in``, ``no-inline-constants``, and \
-                \``preserve-logging``."
+                \Implies `no-relaxed-float-in`, `no-inline-constants`, and \
+                \`preserve-logging`."
            in ( k
               , PluginOption
                     typeRep
@@ -188,7 +188,7 @@ pluginOptions =
               desc =
                 "Always inline constants. Inlining constants always reduces script \
                 \costs slightly, but may increase script sizes if a large constant \
-                \is used more than once. Implied by ``no-conservative-optimisation``."
+                \is used more than once. Implied by `no-conservative-optimisation`."
            in (k, PluginOption typeRep (setTrue k) posInlineConstants desc [])
         , let k = "optimize"
               desc = "Run optimization passes such as simplification and floating let-bindings."
@@ -250,15 +250,15 @@ pluginOptions =
               desc =
                 "Use a more aggressive float-in pass, which often leads to reduced costs \
                 \but may occasionally lead to slightly increased costs. Implied by \
-                \``no-conservative-optimisation``."
+                \`no-conservative-optimisation`."
            in (k, PluginOption typeRep (setTrue k) posRelaxedFloatin desc [])
         , let k = "preserve-logging"
               desc =
                 "Turn off optimisations that may alter (i.e., add, remove or change the \
-                \order of) trace messages. Implied by ``conservative-optimisation``."
+                \order of) trace messages. Implied by `conservative-optimisation`."
            in (k, PluginOption typeRep (setTrue k) posPreserveLogging desc [])
         , let k = "remove-trace"
-              desc = "Eliminate calls to ``trace`` from Plutus Core"
+              desc = "Eliminate calls to `trace` from Plutus Core"
            in (k, PluginOption typeRep (setTrue k) posRemoveTrace desc [])
         , let k = "dump-compilation-trace"
               desc = "Dump compilation trace for debugging"