Merge branch 'main' of github.com:elastic/docs-builder into add-migration-guide

Author: bmorelli25

README.md

@@ -63,7 +63,7 @@ Through the `serve` command you can continuously and partially compile your docu
 
 ```bash
 docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.artifacts" \
-  --expose 8080 ghcr.io/elastic/docs-builder:edge serve
+  -p 8080:8080 ghcr.io/elastic/docs-builder:edge serve
 ```
 
 Each page is compiled on demand as you browse http://localhost:8080 and is never cached so changes to files and 
@@ -148,4 +148,4 @@ The resulting binary `./.artifacts/publish/docs-builder` will run on machines wi
 To test performance it's best to build the binary and run outside of docker:
 
 For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to 
-existing surveyed tools
+existing surveyed tools

src/Elastic.Markdown/BuildContext.cs

@@ -42,9 +42,10 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
 		ReadFileSystem = readFileSystem;
 		WriteFileSystem = writeFileSystem;
 
-		var docsFolder = FindDocsFolderFromRoot();
-
-		SourcePath = !string.IsNullOrWhiteSpace(source) ? ReadFileSystem.DirectoryInfo.New(source) : docsFolder;
+		var rootFolder = !string.IsNullOrWhiteSpace(source)
+			? ReadFileSystem.DirectoryInfo.New(source)
+			: ReadFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName, "docs"));
+		SourcePath = FindDocsFolderFromRoot(rootFolder);
 
 		OutputPath = !string.IsNullOrWhiteSpace(output)
 			? WriteFileSystem.DirectoryInfo.New(output)
@@ -59,12 +60,14 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
 		Git = GitConfiguration.Create(ReadFileSystem);
 	}
 
-	private IDirectoryInfo FindDocsFolderFromRoot()
+	private IDirectoryInfo FindDocsFolderFromRoot(IDirectoryInfo rootPath)
 	{
-		var defaultDocsFolder = ReadFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName, "docs"));
-		var root = ReadFileSystem.DirectoryInfo.New(Paths.Root.FullName);
-		var docsFolder = root.EnumerateFiles("docset.yml", SearchOption.AllDirectories).FirstOrDefault();
-		return docsFolder?.Directory ?? defaultDocsFolder;
+		if (rootPath.Exists &&
+		    ReadFileSystem.File.Exists(Path.Combine(rootPath.FullName, "docset.yml")))
+			return rootPath;
+
+		var docsFolder = rootPath.EnumerateFiles("docset.yml", SearchOption.AllDirectories).FirstOrDefault();
+		return docsFolder?.Directory ?? throw new Exception($"Can not locate docset.yml file in '{rootPath}'");
 	}
 
 }

src/Elastic.Markdown/IO/ConfigurationFile.cs

@@ -49,7 +49,10 @@ public ConfigurationFile(IFileInfo sourceFile, IDirectoryInfo rootPath, BuildCon
 		yaml.Load(textReader);
 
 		if (yaml.Documents.Count == 0)
+		{
 			context.EmitWarning(sourceFile, "empty configuration");
+			return;
+		}
 
 		// Examine the stream
 		var mapping = (YamlMappingNode)yaml.Documents[0].RootNode;

src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs

@@ -34,7 +34,7 @@ public string Title
 	public override void FinalizeAndValidate(ParserContext context)
 	{
 		CrossReferenceName = Properties.GetValueOrDefault("name");
-		DropdownOpen = PropBool("open");
+		DropdownOpen = TryPropBool("open");
 		if (DropdownOpen.HasValue)
 			Classes = "dropdown";
 	}

src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs

@@ -93,6 +93,16 @@ protected bool PropBool(params string[] keys)
 		return bool.TryParse(value, out var result) && result;
 	}
 
+	protected bool? TryPropBool(params string[] keys)
+	{
+		var value = Prop(keys);
+		if (string.IsNullOrEmpty(value))
+			return keys.Any(k => Properties.ContainsKey(k)) ? true : null;
+
+		return bool.TryParse(value, out var result) ? result : null;
+	}
+
+
 	protected string? Prop(params string[] keys)
 	{
 		foreach (var key in keys)

tests/Elastic.Markdown.Tests/OutputDirectoryTests.cs

@@ -18,6 +18,7 @@ public async Task CreatesDefaultOutputDirectory()
 		var logger = new TestLoggerFactory(output);
 		var fileSystem = new MockFileSystem(new Dictionary<string, MockFileData>
 		{
+			{ "docs/source/docset.yml", new MockFileData("") },
 			{ "docs/source/index.md", new MockFileData("test") }
 		}, new MockFileSystemOptions
 		{