Reformat docs and add a new CLI option (#7566)

NethermindEth · Oct 10, 2024 · e6d7733 · e6d7733
1 parent 7ef9398
commit e6d7733
Show file tree

Hide file tree

Showing 12 changed files with 55 additions and 49 deletions.
diff --git a/.github/workflows/build-tools.yml b/.github/workflows/build-tools.yml
@@ -17,7 +17,7 @@ jobs:
       matrix:
         config: [release]
         project:
-          - docgen/DocGen.sln
+          - DocGen/DocGen.sln
           - HiveCompare/HiveCompare.sln
           - HiveConsensusWorkflowGenerator/HiveConsensusWorkflowGenerator.csproj
           - Nethermind.Tools.Kute/Nethermind.Tools.Kute.csproj

diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml
@@ -41,15 +41,15 @@ jobs:
           global-json-file: n/global.json
       - name: Build DocGen
         working-directory: n
-        run: dotnet build tools/docgen/DocGen.csproj -c release -o docgen
+        run: dotnet build tools/DocGen/DocGen.csproj -c release -o DocGen
       - name: Generate docs
-        run: n/docgen/DocGen $GITHUB_WORKSPACE/d --config --jsonrpc --metrics
+        run: n/DocGen/DocGen $GITHUB_WORKSPACE/d --config --jsonrpc --metrics
       - name: Tag a new version
         if: github.event_name == 'release' && !github.event.release.prerelease
         working-directory: d
         run: |
           npm i
-          npm run docusaurus docs:version v${{ github.event.release.tag_name }}
+          npm run docusaurus docs:version ${{ github.event.release.tag_name }}
       - name: Create a pull request
         working-directory: d
         env:

diff --git a/tools/docgen/.editorconfig → tools/DocGen/.editorconfig b/tools/docgen/.editorconfig → tools/DocGen/.editorconfig
diff --git a/tools/docgen/ConfigGenerator.cs → tools/DocGen/ConfigGenerator.cs b/tools/docgen/ConfigGenerator.cs → tools/DocGen/ConfigGenerator.cs
@@ -88,13 +88,7 @@ private static void WriteMarkdown(StreamWriter file, Type configType)
         var moduleName = configType.Name[1..].Replace("Config", null);
 
         file.WriteLine($"""
-            <details>
-            <summary className="nd-details-heading">
-
-            #### {moduleName}
-
-            </summary>
-            <p>
+            ### {moduleName}
 
             """);
 
@@ -107,10 +101,32 @@ private static void WriteMarkdown(StreamWriter file, Type configType)
 
             var description = itemAttr.Description.Replace("\n", "\n  ").TrimEnd(' ');
 
-            file.Write($"""
-                - **`--{moduleName}.{prop.Name} <value>`** `NETHERMIND_{moduleName.ToUpperInvariant()}CONFIG_{prop.Name.ToUpperInvariant()}`
-
-                  {description}
+            file.Write($$"""
+                - #### `{{moduleName}}.{{prop.Name}}` \{#{{moduleName.ToLowerInvariant()}}-{{prop.Name.ToLowerInvariant()}}\}
+
+                  <Tabs groupId="usage">
+                  <TabItem value="cli" label="CLI">
+                  ```
+                  --{{moduleName}}.{{prop.Name}} <value>
+                  ```
+                  </TabItem>
+                  <TabItem value="env" label="Environment variable">
+                  ```
+                  NETHERMIND_{{moduleName.ToUpperInvariant()}}CONFIG_{{prop.Name.ToUpperInvariant()}}=<value>
+                  ```
+                  </TabItem>
+                  <TabItem value="config" label="Configuration file">
+                  ```json
+                  {
+                    "{{moduleName}}": {
+                      "{{prop.Name}}": <value>
+                    }
+                  }
+                  ```
+                  </TabItem>
+                  </Tabs>
+
+                  {{description}}
                 """);
 
             var startsFromNewLine = WriteAllowedValues(file, prop.PropertyType) || description.EndsWith('\n');
@@ -121,11 +137,7 @@ private static void WriteMarkdown(StreamWriter file, Type configType)
             file.WriteLine();
         }
 
-        file.WriteLine("""
-            </p>
-            </details>
-
-            """);
+        file.WriteLine();
     }
 
     private static bool WriteAllowedValues(StreamWriter file, Type type)

diff --git a/tools/docgen/DBSizeGenerator.cs → tools/DocGen/DBSizeGenerator.cs b/tools/docgen/DBSizeGenerator.cs → tools/DocGen/DBSizeGenerator.cs
@@ -8,7 +8,6 @@ namespace Nethermind.DocGen;
 
 internal static class DBSizeGenerator
 {
-    private const string _chainSizesDir = "chainSizes";
     private const string _startMark = "<!--[start autogen]-->";
     private const string _endMark = "<!--[end autogen]-->";
 
@@ -23,7 +22,7 @@ internal static class DBSizeGenerator
         "blobTransactions"
     ];
 
-    internal static void Generate(string path)
+    internal static void Generate(string docsPath, string? dbSizeSourcePath)
     {
         IList<string> chainOrder =
         [
@@ -36,9 +35,10 @@ internal static void Generate(string path)
             "volta"
         ];
 
-        var chainSizesPath = Path.Join(AppDomain.CurrentDomain.BaseDirectory, _chainSizesDir);
+        dbSizeSourcePath ??= AppDomain.CurrentDomain.BaseDirectory;
+
         var chains = Directory
-            .GetFiles(chainSizesPath)
+            .GetFiles(dbSizeSourcePath)
             .Select(Path.GetFileNameWithoutExtension)
             .OrderBy(c =>
             {
@@ -48,14 +48,14 @@ internal static void Generate(string path)
             })
             .ToList();
 
-        GenerateFile(Path.Join(path, "docs", "fundamentals"), chains!);
-        GenerateFile(Path.Join(path, "versioned_docs", $"version-{GetLatestVersion(path)}", "fundamentals"), chains!);
+        GenerateFile(Path.Join(docsPath, "docs", "fundamentals"), dbSizeSourcePath, chains!);
+        GenerateFile(Path.Join(docsPath, "versioned_docs", $"version-{GetLatestVersion(docsPath)}", "fundamentals"), dbSizeSourcePath, chains!);
     }
 
-    private static void GenerateFile(string path, IList<string> chains)
+    private static void GenerateFile(string docsPath, string dbSizeSourcePath, IList<string> chains)
     {
-        var fileName = Path.Join(path, "database.md");
-        var tempFileName = Path.Join(path, "~database.md");
+        var fileName = Path.Join(docsPath, "database.md");
+        var tempFileName = Path.Join(docsPath, "~database.md");
 
         // Delete the temp file if it exists
         File.Delete(tempFileName);
@@ -77,7 +77,7 @@ private static void GenerateFile(string path, IList<string> chains)
 
         writeStream.WriteLine();
 
-        WriteMarkdown(writeStream, chains!);
+        WriteMarkdown(writeStream, dbSizeSourcePath, chains!);
 
         var skip = true;
 
@@ -103,22 +103,23 @@ private static void GenerateFile(string path, IList<string> chains)
         AnsiConsole.MarkupLine($"[green]Updated[/] {fileName}");
     }
 
-    private static void WriteMarkdown(StreamWriter file, IList<string> chains)
+    private static void WriteMarkdown(StreamWriter file, string dbSizeSourcePath, IList<string> chains)
     {
         file.WriteLine("<Tabs>");
 
         foreach (var chain in chains)
-            WriteChainSize(file, chain);
+            WriteChainSize(file, dbSizeSourcePath, chain);
 
         file.WriteLine("""
             </Tabs>
 
             """);
     }
 
-    private static void WriteChainSize(StreamWriter file, string chain)
+    private static void WriteChainSize(StreamWriter file, string dbSizeSourcePath, string chain)
     {
-        using var json = JsonDocument.Parse(File.ReadAllText($"{_chainSizesDir}/{chain}.json"));
+        var path = Path.Join(dbSizeSourcePath, $"{chain}.json");
+        using var json = JsonDocument.Parse(File.ReadAllText(path));
 
         if (json.RootElement.ValueKind != JsonValueKind.Object)
             return;

diff --git a/tools/docgen/DocGen.csproj → tools/DocGen/DocGen.csproj b/tools/docgen/DocGen.csproj → tools/DocGen/DocGen.csproj
diff --git a/tools/docgen/DocGen.sln → tools/DocGen/DocGen.sln b/tools/docgen/DocGen.sln → tools/DocGen/DocGen.sln
diff --git a/tools/docgen/JsonRpcGenerator.cs → tools/DocGen/JsonRpcGenerator.cs b/tools/docgen/JsonRpcGenerator.cs → tools/DocGen/JsonRpcGenerator.cs
diff --git a/tools/docgen/MetricsGenerator.cs → tools/DocGen/MetricsGenerator.cs b/tools/docgen/MetricsGenerator.cs → tools/DocGen/MetricsGenerator.cs
@@ -85,13 +85,7 @@ private static void WriteMarkdown(StreamWriter file, Type metricsType)
             return;
 
         file.WriteLine($"""
-            <details>
-            <summary className="nd-details-heading">
-
-            #### {GetNamespace(metricsType.FullName)}
-
-            </summary>
-            <p>
+            ### {GetNamespace(metricsType.FullName)}
 
             """);
 
@@ -100,7 +94,7 @@ private static void WriteMarkdown(StreamWriter file, Type metricsType)
             var attr = prop.GetCustomAttribute<DescriptionAttribute>();
             var param = _regex.Replace(prop.Name, m => $"_{m.Value.ToLowerInvariant()}");
 
-            file.WriteLine($"- **`nethermind{param}`**");
+            file.WriteLine($"- #### `nethermind{param}` \\{{#{param[1..]}\\}}");
 
             if (!string.IsNullOrWhiteSpace(attr?.Description))
                 file.WriteLine($"""
@@ -110,12 +104,7 @@ private static void WriteMarkdown(StreamWriter file, Type metricsType)
                     """);
         }
 
-        file.WriteLine("""
-
-            </p>
-            </details>
-
-            """);
+        file.WriteLine();
     }
 
     private static string? GetNamespace(string? fullTypeName)

diff --git a/tools/docgen/Program.cs → tools/DocGen/Program.cs b/tools/docgen/Program.cs → tools/DocGen/Program.cs
@@ -30,7 +30,7 @@ public override int Execute(CommandContext context, AppSettings settings)
             ConfigGenerator.Generate(settings.DocsPath);
 
         if (settings.GenerateDBSize)
-            DBSizeGenerator.Generate(settings.DocsPath);
+            DBSizeGenerator.Generate(settings.DocsPath, settings.DBSizeSourcePath);
 
         if (settings.GenerateJsonRpc)
             JsonRpcGenerator.Generate(settings.DocsPath);
@@ -44,6 +44,10 @@ public override int Execute(CommandContext context, AppSettings settings)
 
 public sealed class AppSettings : CommandSettings
 {
+    [Description("Path to the directory with DB size files")]
+    [CommandOption("--dbsize-src")]
+    public string? DBSizeSourcePath { get; init; }
+
     [Description("Path to the docs")]
     [CommandArgument(0, "[docspath]")]
     public string? DocsPath { get; init; }

diff --git a/tools/docgen/Properties/launchSettings.json → tools/DocGen/Properties/launchSettings.json b/tools/docgen/Properties/launchSettings.json → tools/DocGen/Properties/launchSettings.json
diff --git a/tools/docgen/nuget.config → tools/DocGen/nuget.config b/tools/docgen/nuget.config → tools/DocGen/nuget.config