diff --git a/README.md b/README.md index d2d4e0781..0a549390a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ This repository is host to: * *`docs-builder`* command line tool to generate single doc-sets (13mb native code, no dependencies) * *`docs-assembler`* command line tool to assemble all the doc sets. (IN PROGRESS) * `elastic/docs-builder@main` Github Action to build and validate a repositories documentation -* *`docs-generator`* command line tool to deterministically generate a docset and incremental updates to generated content ## Command line interface diff --git a/build/Targets.fs b/build/Targets.fs index 61055a6b4..f566ec9ac 100644 --- a/build/Targets.fs +++ b/build/Targets.fs @@ -20,7 +20,6 @@ let private clean _ = removeArtifacts "release-notes" removeArtifacts "tests" removeArtifacts "docs-builder" - removeArtifacts "docs-generator" let private compile _ = exec { run "dotnet" "build" "-c" "release" } @@ -58,7 +57,6 @@ let private pristineCheck (arguments:ParseResults) = let private publishBinaries _ = exec { run "dotnet" "publish" "src/docs-builder/docs-builder.csproj" } - exec { run "dotnet" "publish" "src/docs-generator/docs-generator.csproj" } exec { run "dotnet" "publish" "src/docs-assembler/docs-assembler.csproj" } Zip.zip ".artifacts/publish/docs-builder/release" @@ -105,7 +103,6 @@ let private publishContainers _ = ] exec { run "dotnet" (args @ registry) } createImage "docs-builder" - createImage "docs-generator" createImage "docs-assembler" let private runTests _ = diff --git a/docs-builder.sln b/docs-builder.sln index 933bb0790..6e7443db5 100644 --- a/docs-builder.sln +++ b/docs-builder.sln @@ -27,15 +27,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{67B576EE EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Markdown.Tests", "tests\Elastic.Markdown.Tests\Elastic.Markdown.Tests.csproj", "{B27C5107-128B-465A-B8F8-8985399E4CFB}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "docs-generator", "src\docs-generator\docs-generator.csproj", "{61904527-9753-4379-B546-56B6A29073AC}" -EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "actions", "actions", "{245023D2-D3CA-47B9-831D-DAB91A2FFDC7}" EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "generator", "generator", "{1C340CCF-9AAC-4163-A7BB-60528076E98B}" - ProjectSection(SolutionItems) = preProject - actions\generator\action.yml = actions\generator\action.yml - EndProjectSection -EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "publish", "publish", "{CD2887E3-BDA9-434B-A5BF-9ED38DE20332}" ProjectSection(SolutionItems) = preProject actions\publish\action.yml = actions\publish\action.yml @@ -81,10 +74,6 @@ Global {B27C5107-128B-465A-B8F8-8985399E4CFB}.Debug|Any CPU.Build.0 = Debug|Any CPU {B27C5107-128B-465A-B8F8-8985399E4CFB}.Release|Any CPU.ActiveCfg = Release|Any CPU {B27C5107-128B-465A-B8F8-8985399E4CFB}.Release|Any CPU.Build.0 = Release|Any CPU - {61904527-9753-4379-B546-56B6A29073AC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {61904527-9753-4379-B546-56B6A29073AC}.Debug|Any CPU.Build.0 = Debug|Any CPU - {61904527-9753-4379-B546-56B6A29073AC}.Release|Any CPU.ActiveCfg = Release|Any CPU - {61904527-9753-4379-B546-56B6A29073AC}.Release|Any CPU.Build.0 = Release|Any CPU {10857974-6CF1-42B5-B793-AAA988BD7348}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {10857974-6CF1-42B5-B793-AAA988BD7348}.Debug|Any CPU.Build.0 = Debug|Any CPU {10857974-6CF1-42B5-B793-AAA988BD7348}.Release|Any CPU.ActiveCfg = Release|Any CPU @@ -106,8 +95,6 @@ Global {4D198E25-C211-41DC-9E84-B15E89BD7048} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A} {01F05AD0-E0E0-401F-A7EC-905928E1E9F0} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A} {B27C5107-128B-465A-B8F8-8985399E4CFB} = {67B576EE-02FA-4F9B-94BC-3630BC09ECE5} - {61904527-9753-4379-B546-56B6A29073AC} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A} - {1C340CCF-9AAC-4163-A7BB-60528076E98B} = {245023D2-D3CA-47B9-831D-DAB91A2FFDC7} {CD2887E3-BDA9-434B-A5BF-9ED38DE20332} = {245023D2-D3CA-47B9-831D-DAB91A2FFDC7} {A2A34BBC-CB5E-4100-9529-A12B6ECB769C} = {245023D2-D3CA-47B9-831D-DAB91A2FFDC7} {28350800-B44B-479B-86E2-1D39E321C0B4} = {BE6011CC-1200-4957-B01F-FCCA10C5CF5A} diff --git a/src/docs-generator/Cli/Commands.cs b/src/docs-generator/Cli/Commands.cs deleted file mode 100644 index 7ac2c4eb9..000000000 --- a/src/docs-generator/Cli/Commands.cs +++ /dev/null @@ -1,158 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -using Actions.Core.Services; -using ConsoleAppFramework; -using Documentation.Generator.Domain; -using Microsoft.Extensions.Logging; - -namespace Documentation.Generator.Cli; - -internal class Commands(ILoggerFactory logger, ICoreService githubActionsService) -{ - private readonly ILogger _logger = logger.CreateLogger(); - - [Command("")] - public async Task Generate( - int? seedFileSystem = null, - int? seedContent = null, - string? output = null, - bool? clear = null, - Cancel ctx = default - ) - { - output ??= githubActionsService.GetInput("output"); - var cleanOutputDirectory = clear ?? true; - var outputFolder = !string.IsNullOrWhiteSpace(output) - ? new DirectoryInfo(output) - : new DirectoryInfo(Path.Combine(Paths.Root.FullName, ".artifacts/docs/markdown")); - var stateFile = new FileInfo(Path.Combine(outputFolder.FullName, "generator.state")); - - LoadStateFromFile(stateFile, clear, ref seedFileSystem, ref cleanOutputDirectory); - - Determinism.Random = new Determinism(seedFileSystem, seedContent); - - _logger.LogInformation( - $"Running generator with file seed: {Determinism.Random.SeedFileSystem} and content seed: {Determinism.Random.SeedContent}"); - - Generators.FolderName.UseSeed(Determinism.Random.SeedFileSystem); - Generators.File.UseSeed(Determinism.Random.SeedFileSystem); - Generators.Section.UseSeed(Determinism.Random.SeedContent); - - Generators.FolderNames = Generators.FolderName - .Generate(Determinism.Random.FileSystem.Number(3, 15)) - .SelectMany(p => Generators.CreateSubPaths(p.Folder, Determinism.Random.FileSystem.Number(0, 3), 0)) - .Distinct() - .ToArray(); - - var folders = new List(); - foreach (var folder in Generators.FolderNames) - { - var mdFolder = new Folder - { - Path = folder, - Files = Generators.File - .Generate(Determinism.Random.FileSystem.Number(1, 4)) - .Select(f => - { - f.Directory = folder; - return f; - }) - .ToArray() - }; - folders.Add(mdFolder); - } - - var files = folders.SelectMany(f => f.Files).ToArray(); - foreach (var folder in folders) - { - foreach (var file in folder.Files) - { - var length = Determinism.Random.Contents.Number(1, 10); - file.Links = Enumerable.Range(0, length) - .Select(i => files[Determinism.Random.Contents.Number(0, files.Length - 1)]) - .Select(f => f.GetRandomLink()) - .ToList(); - file.RewriteLinksIntoSections(); - } - } - - _logger.LogInformation($"Writing to {outputFolder.FullName}"); - - if (outputFolder.Exists && cleanOutputDirectory) - Directory.Delete(outputFolder.FullName, true); - - var updateFiles = files - .Where(f => cleanOutputDirectory || f.IncludeInUpdate) - .ToArray(); - foreach (var file in updateFiles) - { - var directory = Path.Combine(outputFolder.FullName, file.Directory); - _logger.LogInformation($"Writing to {directory}"); - Directory.CreateDirectory(directory); - - WriteMarkdownFile(outputFolder, file); - } - - var name = $"random-docset-{Determinism.Random.SeedFileSystem}-{Determinism.Random.SeedFileSystem}"; - WriteIndexMarkdownFile(name, outputFolder); - - var docset = Path.Combine(outputFolder.FullName, "docset.yml"); - File.WriteAllText(docset, $"project: {name}{Environment.NewLine}"); - File.AppendAllText(docset, $"toc:{Environment.NewLine}"); - foreach (var folder in folders) - File.AppendAllText(docset, $" - folder: {folder.Path}{Environment.NewLine}"); - - File.AppendAllText(docset, $" - file: index.md{Environment.NewLine}"); - File.AppendAllText(docset, Environment.NewLine); - - File.WriteAllText(stateFile.FullName, $"{Determinism.Random.SeedFileSystem}|{Determinism.Random.SeedContent}"); - - return await Task.FromResult(0); - } - - private void WriteIndexMarkdownFile(string name, DirectoryInfo directoryInfo) - { - var filePath = Path.Combine(directoryInfo.FullName, "index.md"); - File.WriteAllText(filePath, - $""" - # {name} Documentation Set - - """); - File.AppendAllText(filePath, "This docset is generated using docs-generator"); - File.AppendAllText(filePath, Environment.NewLine); - } - - private void WriteMarkdownFile(DirectoryInfo directoryInfo, MarkdownFile markdownFile) - { - var filePath = Path.Combine(directoryInfo.FullName, markdownFile.RelativePath); - File.WriteAllText(filePath, - $""" - # {markdownFile.Title} - - """); - foreach (var section in markdownFile.Sections) - { - File.AppendAllText(filePath, Environment.NewLine); - var header = new string('#', section.Level); - File.AppendAllText(filePath, $"{header} {section.Header}{Environment.NewLine}"); - File.AppendAllText(filePath, Environment.NewLine); - - File.AppendAllText(filePath, section.Paragraphs); - File.AppendAllText(filePath, Environment.NewLine); - } - } - - private void LoadStateFromFile(FileInfo fileInfo, bool? clear, ref int? seedFs, ref bool cleanOutput) - { - if (!fileInfo.Exists) - return; - var state = File.ReadAllText(fileInfo.FullName).Split("|"); - if (state.Length != 2) - return; - seedFs ??= int.TryParse(state[0], out var seed) ? seed : seedFs; - _logger.LogInformation($"Seeding with {seedFs} from previous run {fileInfo.FullName}"); - cleanOutput = clear ?? false; - } -} diff --git a/src/docs-generator/Domain/Determinism.cs b/src/docs-generator/Domain/Determinism.cs deleted file mode 100644 index 5d690fb38..000000000 --- a/src/docs-generator/Domain/Determinism.cs +++ /dev/null @@ -1,34 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -using Bogus; - -namespace Documentation.Generator.Domain; - -public record Determinism -{ - public Determinism(int? seedFileSystem, int? seedContent) - { - var randomizer = new Randomizer(); - SeedFileSystem = seedFileSystem ?? randomizer.Int(1, int.MaxValue); - SeedContent = seedContent ?? randomizer.Int(1, int.MaxValue); - FileSystem = new Randomizer(SeedFileSystem); - Contents = new Randomizer(SeedContent); - - ContentProbability = Contents.Float(0.001f, Contents.Float(0.1f)); - FileProbability = FileSystem.Float(0.001f, Contents.Float(0.1f)); - } - - public int SeedFileSystem { get; } - public int SeedContent { get; } - - - public Randomizer FileSystem { get; } - public Randomizer Contents { get; } - - public float ContentProbability { get; } - public float FileProbability { get; } - - public static Determinism Random { get; set; } = new(null, null); -} diff --git a/src/docs-generator/Domain/Generators.cs b/src/docs-generator/Domain/Generators.cs deleted file mode 100644 index b5ac444b1..000000000 --- a/src/docs-generator/Domain/Generators.cs +++ /dev/null @@ -1,49 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -using Soenneker.Utils.AutoBogus; - -namespace Documentation.Generator.Domain; - -public static class Generators -{ - public static AutoFaker FolderName { get; } = new(); - public static AutoFaker
Section { get; } = new(); - public static AutoFaker File { get; } = new(); - - static Generators() - { - FolderName - .RuleFor(p => p.Folder, f => f.Lorem.Slug(1)); - - Section - .RuleFor(p => p.Paragraphs, f => f.Lorem.Paragraphs(f.Random.Number(1, 10))) - .RuleFor(p => p.Level, f => f.Random.Number(2, 4)); - - File - .Ignore(p => p.Links) - .Ignore(p => p.Directory) - .RuleFor(p => p.FileName, f => f.System.FileName("md")) - .RuleFor(p => p.IncludeInUpdate, f => Determinism.Random.Contents.Float() <= Determinism.Random.ContentProbability) - .RuleFor(p => p.Sections, f => Section.Generate(Determinism.Random.Contents.Number(1, 12)).ToArray()); - } - - public static IEnumerable CreateSubPaths(string parent, int maxDepth, int currentDepth) - { - yield return parent; - if (currentDepth == maxDepth) - yield break; - var subFolders = FolderName.Generate(Determinism.Random.FileSystem.Number(0, 4)); - foreach (var subFolder in subFolders) - { - var path = $"{parent}/{subFolder.Folder}"; - yield return path; - var subPaths = CreateSubPaths(path, maxDepth, currentDepth + 1); - foreach (var p in subPaths) - yield return p; - } - } - - public static string[] FolderNames { get; set; } = []; -} diff --git a/src/docs-generator/Domain/MarkdownFile.cs b/src/docs-generator/Domain/MarkdownFile.cs deleted file mode 100644 index 601ce6492..000000000 --- a/src/docs-generator/Domain/MarkdownFile.cs +++ /dev/null @@ -1,54 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -using Slugify; -using Soenneker.Utils.AutoBogus; - -namespace Documentation.Generator.Domain; - -public record MarkdownFile -{ - public required string FileName { get; init; } - public required Section[] Sections { get; init; } - public required string Title { get; init; } - - public string RelativePath => $"{Directory}/{FileName}"; - - public required bool IncludeInUpdate { get; init; } = true; - - public string Directory { get; set; } = string.Empty; - public List Links { get; set; } = []; - - public void RewriteLinksIntoSections() - { - var linksLength = Links.Count; - var sectionsLength = Sections.Length; - for (var i = 0; i < linksLength; i++) - { - var link = Links[i]; - var section = Sections[Determinism.Random.Contents.Number(0, sectionsLength - 1)]; - var words = section.Paragraphs.Split(" "); - var w = Determinism.Random.Contents.Number(0, words.Length - 1); - var word = words[w]; - words[w] = $"[{word}](/{link})"; - section.Paragraphs = string.Join(" ", words); - } - } - - - public string GetRandomLink() - { - //TODO since updates rewrite section headers old docs might - //no longer validate so we always link to whole files - return RelativePath; - /* - var sectionLink = Determinism.Random.Contents.Bool(0.8f); - if (!sectionLink) return RelativePath; - var section = Sections[Determinism.Random.Contents.Number(0, Sections.Length - 1)]; - return $"{RelativePath}#{Generators.Slug.GenerateSlug(section.Header)}"; - */ - - } -} - diff --git a/src/docs-generator/Domain/Path.cs b/src/docs-generator/Domain/Path.cs deleted file mode 100644 index 308a6c08e..000000000 --- a/src/docs-generator/Domain/Path.cs +++ /dev/null @@ -1,30 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -namespace Documentation.Generator.Domain; - -public static class Paths -{ - private static DirectoryInfo RootDirectoryInfo() - { - var directory = new DirectoryInfo(Directory.GetCurrentDirectory()); - while (directory != null && - (directory.GetFiles("*.sln").Length == 0 || directory.GetDirectories(".git").Length == 0)) - directory = directory.Parent; - return directory ?? new DirectoryInfo(Directory.GetCurrentDirectory()); - } - - public static readonly DirectoryInfo Root = RootDirectoryInfo(); -} - -public record FolderName -{ - public required string Folder { get; init; } -} - -public record Folder -{ - public required string Path { get; init; } - public required MarkdownFile[] Files { get; init; } -} diff --git a/src/docs-generator/Domain/Section.cs b/src/docs-generator/Domain/Section.cs deleted file mode 100644 index 18558ca8f..000000000 --- a/src/docs-generator/Domain/Section.cs +++ /dev/null @@ -1,15 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -namespace Documentation.Generator.Domain; - -public record Section -{ - public required string Header { get; init; } - - public required int Level { get; init; } - - public required string Paragraphs { get; set; } - -} diff --git a/src/docs-generator/Program.cs b/src/docs-generator/Program.cs deleted file mode 100644 index 6f8a123f7..000000000 --- a/src/docs-generator/Program.cs +++ /dev/null @@ -1,43 +0,0 @@ -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information -// Licensed to Elasticsearch B.V under one or more agreements. -// Elasticsearch B.V licenses this file to you under the Apache 2.0 License. -// See the LICENSE file in the project root for more information - -// ReSharper disable RedundantLambdaParameterType - -using Actions.Core.Extensions; -using ConsoleAppFramework; -using Documentation.Generator.Cli; -using Documentation.Generator.Domain; -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; - -var services = new ServiceCollection(); -services.AddGitHubActionsCore(); -services.AddLogging(x => -{ - x.ClearProviders(); - x.SetMinimumLevel(LogLevel.Information); - x.AddSimpleConsole(c => - { - c.SingleLine = true; - c.IncludeScopes = true; - c.UseUtcTimestamp = true; - c.TimestampFormat = Environment.UserInteractive ? ":: " : "[yyyy-MM-ddTHH:mm:ss] "; - }); -}); - -await using var serviceProvider = services.BuildServiceProvider(); -var logger = serviceProvider.GetRequiredService>(); -ConsoleApp.ServiceProvider = serviceProvider; -var isHelp = args.Contains("-h") || args.Contains("--help"); -if (!isHelp) - ConsoleApp.Log = msg => logger.LogInformation(msg); -ConsoleApp.LogError = msg => logger.LogError(msg); - -var app = ConsoleApp.Create(); -app.Add(); - -await app.RunAsync(args).ConfigureAwait(false); diff --git a/src/docs-generator/docs-generator.csproj b/src/docs-generator/docs-generator.csproj deleted file mode 100644 index fb35054c3..000000000 --- a/src/docs-generator/docs-generator.csproj +++ /dev/null @@ -1,31 +0,0 @@ - - - - net9.0 - Exe - docs-generator - Documentation.Generator - true - - false - true - true - - true - true - - - - - all - runtime; build; native; contentfiles; analyzers; buildtransitive - - - - - - - - - -