Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions cmf-cli/Handlers/PackageType/HelpMkDocsPackageTypeHandler.cs
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage)
{
new Step(StepType.DeployFiles)
{
ContentPath = "site/**",
ContentPath = "**",
TargetDirectory = "/"
}
}
Expand Down Expand Up @@ -105,6 +105,30 @@ public HelpMkDocsPackageTypeHandler(CmfPackage cmfPackage) : base(cmfPackage)
];
}

/// <inheritdoc />
internal override List<FileToPack> GetContentToPack(IDirectoryInfo packageOutputDir)
{
var files = base.GetContentToPack(packageOutputDir);
var siteDirectory = fileSystem.Path.Join(CmfPackage.GetFileInfo().Directory.FullName, "site");

foreach (var file in files)
{
var relativePath = fileSystem.Path.GetRelativePath(siteDirectory, file.Source.FullName);
if (fileSystem.Path.IsPathRooted(relativePath)
|| relativePath == ".."
|| relativePath.StartsWith(".." + fileSystem.Path.DirectorySeparatorChar, StringComparison.Ordinal))
{
continue;
}

// DeployFiles preserves archive paths. Remove only the build output wrapper,
// keeping links between pages, assets and search files unchanged.
file.Target = fileSystem.FileInfo.New(fileSystem.Path.Join(packageOutputDir.FullName, relativePath));
}

return files;
}

/// <summary>
/// Packs the generated MkDocs site.
/// </summary>
Expand Down Expand Up @@ -151,7 +175,7 @@ public override void RestoreDependencies(Uri[] repoUris)

if (temporaryFolderForUnziping.Exists)
{
// Each restored mkdocs zip unpacks site, docs and manifest.
// Each restored MkDocs zip contains the website, docs and manifest.
// We only care about the docs folder
var dependencyDocsFolders = fileSystem.Directory.GetDirectories(temporaryFolderForUnziping.FullName, "docs", SearchOption.AllDirectories);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"contentToPack": [
{
"source": "site/**",
"target": "site"
"target": ""
},
{
"source": "docs/<%= $CLI_PARAM_ProjectName %>/**",
Expand Down
17 changes: 17 additions & 0 deletions docs/src/03-explore/commands/pack.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,20 @@ Name | Description


<!-- END USAGE -->

## MES v12 MkDocs Help packages

`cmf build` keeps MkDocs output in `site/`. When packing a v12 Help package,
`cmf pack` places the selected contents of `site/` at the archive root, preserving
all relative paths between HTML pages, assets and search files. Documentation
sources remain under `docs/<project>/` for dependency restoration.

This also applies to existing packages whose `contentToPack` maps `site/**` to
`site`; no project-specific name or source configuration change is required.
New Help templates map `site/**` to an empty target explicitly.

The default `DeployFiles` step uses `contentPath: "**"`, so extraction into
`/app` produces `/app/index.html`, matching the Product Help nginx configuration.
This step also includes the packaged documentation sources. If you override the
default steps, update any `site/**` filters to match the new archive layout.
Help packages for MES versions before v12 retain their existing behavior.
42 changes: 34 additions & 8 deletions tests/Specs/Pack.cs
Original file line number Diff line number Diff line change
Expand Up @@ -1374,8 +1374,11 @@ public void Help_v12_MkDocsPack_FailsWhenSiteWasNotBuilt()
exception.Message.Should().Contain("Could not find MkDocs site");
}

[Fact]
public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
[Theory]
[InlineData("site")]
[InlineData("")]
[InlineData("site/features/custom-feature")]
public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist(string siteTarget)
{
var fileSystem = new MockFileSystem(new Dictionary<string, MockFileData>
{
Expand All @@ -1387,21 +1390,25 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
""version"": ""1.0.0"",
""packageType"": ""Help"",
""contentToPack"": [
{ ""source"": ""site/**"", ""target"": ""site"" },
{ ""source"": ""site/**"", ""target"": """ + siteTarget + @""" },
{ ""source"": ""docs/cmf/**"", ""target"": ""docs/cmf"" }
]
}") },
{ "/repo/Cmf.Custom.Help/docs/requirements.txt", new MockFileData("mkdocs-material") },
{ "/repo/Cmf.Custom.Help/docs/cmf/index.md", new MockFileData("# Help") },
{ "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("<html>Help</html>") },
{ "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{}") },
{ "/repo/Cmf.Custom.Help/site/index.html", new MockFileData("<link href=\"assets/theme.css\" rel=\"stylesheet\"><a href=\"guide/\">Guide</a><script src=\"assets/search.js\"></script>") },
{ "/repo/Cmf.Custom.Help/site/search/search_index.json", new MockFileData("{\"docs\":[{\"location\":\"guide/\",\"title\":\"Guide\"}]}") },
{ "/repo/Cmf.Custom.Help/site/guide/index.html", new MockFileData("<a href=\"../\">Home</a><link href=\"../assets/theme.css\" rel=\"stylesheet\">") },
{ "/repo/Cmf.Custom.Help/site/assets/theme.css", new MockFileData("body { background: url(images/icon.svg); }") },
{ "/repo/Cmf.Custom.Help/site/assets/images/icon.svg", new MockFileData("<svg/>") },
{ "/repo/Cmf.Custom.Help/site/assets/search.js", new MockFileData("fetch('search/search_index.json')") },
{ "/repo/output", new MockDirectoryData() }
});

ExecutionContext.Initialize(fileSystem);

var packageTypeHandler = PackageTypeFactory.GetPackageTypeHandler(
fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json")) as HelpMkDocsPackageTypeHandler;
fileSystem.FileInfo.New("/repo/Cmf.Custom.Help/cmfpackage.json"), setDefaultValues: true) as HelpMkDocsPackageTypeHandler;

packageTypeHandler.Pack(
fileSystem.DirectoryInfo.New("/repo/package"),
Expand All @@ -1411,9 +1418,28 @@ public void Help_v12_MkDocsPack_SucceedsWhenSiteAndDocsExist()
packageZip.Exists.Should().BeTrue("Package zip file should be created");

using var zip = new ZipArchive(packageZip.OpenRead(), ZipArchiveMode.Read);
zip.GetEntry("site/index.html").Should().NotBeNull();
zip.GetEntry("index.html").Should().NotBeNull();
zip.GetEntry("site/index.html").Should().BeNull();
zip.GetEntry("docs/cmf/index.md").Should().NotBeNull();
zip.GetEntry("site/search/search_index.json").Should().NotBeNull();
zip.GetEntry("search/search_index.json").Should().NotBeNull();

// Keep every generated file byte-for-byte, preserving relative links and search locations.
foreach (var source in fileSystem.Directory.GetFiles("/repo/Cmf.Custom.Help/site", "*", SearchOption.AllDirectories))
{
var relativePath = fileSystem.Path.GetRelativePath("/repo/Cmf.Custom.Help/site", source).Replace('\\', '/');
var entry = zip.GetEntry(relativePath);
entry.Should().NotBeNull();
using var reader = new StreamReader(entry.Open());
reader.ReadToEnd().Should().Be(fileSystem.File.ReadAllText(source));
}

using var manifestReader = new StreamReader(zip.GetEntry("manifest.xml").Open());
var manifest = XDocument.Parse(manifestReader.ReadToEnd());
var step = manifest.Descendants("step").Single(e => (string)e.Attribute("type") == "DeployFiles");
((string)step.Attribute("contentPath")).Should().Be("**");
((string)step.Attribute("targetDirectory")).Should().Be("/");
fileSystem.File.ReadAllText("/repo/Cmf.Custom.Help/cmfpackage.json").Should().Contain("\"target\": \"" + siteTarget + "\"");

}


Expand Down
50 changes: 47 additions & 3 deletions tests/Specs/Restore.cs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
using System.IO.Abstractions.TestingHelpers;
using Cmf.CLI.Core.Services;
using Microsoft.Extensions.DependencyInjection;
using Moq;
using tests.Objects;
using Xunit;
using Assert = tests.AssertWithMessage;
Expand Down Expand Up @@ -201,8 +202,23 @@ public void RestoreDependencies_RepoNotFound()
logWriter.ToString().Should().Contain("No present remote dependencies to restore. Exiting...");
}

[Fact]
public void RestoreDependencies_HelpMkDocs()
[Theory]
[InlineData(false)]
[InlineData(true)]
public void RestoreDependencies_HelpMkDocs(bool useRepositoryClients)
{
var previousServiceProvider = ExecutionContext.ServiceProvider;
try
{
RestoreDependencies_HelpMkDocsInternal(useRepositoryClients);
}
finally
{
ExecutionContext.ServiceProvider = previousServiceProvider;
}
}

private void RestoreDependencies_HelpMkDocsInternal(bool useRepositoryClients)
{
var gitRepo = MockUnixSupport.Path(@"c:\test");
var ciRepo = MockUnixSupport.Path(@"c:\cirepo");
Expand Down Expand Up @@ -234,20 +250,27 @@ public void RestoreDependencies_HelpMkDocs()
}") },
{ $"{gitRepo}/requirements.txt", new MockFileData("mkdocs") },
{ $"{gitRepo}/docs/other.txt", new MockFileData("original other") },
{ $"{gitRepo}/docs/LocalProject/index.md", new MockFileData("# Local project documentation") },
{ $"{gitRepo}/docs/MyProject/old-file.txt", new MockFileData("old content") },
{ $"{gitRepo}/docs/MyProject/index.html", new MockFileData("<html>old index</html>") },
{ $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip", new MockFileData(new DFPackageBuilder()
.CreateEntry("manifest.xml", @"<?xml version=""1.0"" encoding=""utf-8""?><deploymentPackage><packageId>Cmf.Custom.Help</packageId><version>1.0.0</version></deploymentPackage>")
.CreateEntry("index.html", "<html>generated website</html>")
.CreateEntry("assets/theme.css", "body {}")
.CreateEntry("search/search_index.json", "{}")
.CreateEntry("docs/MyProject/index.html", "<html>index</html>")
.CreateEntry("docs/MyProject/getting-started.html", "<html>getting started</html>")
.CreateEntry("docs/MyProject/reference.md", "# Reference")
.CreateEntry("docs/Features/OtherFeature/index.md", "# Feature documentation")
.CreateEntry("docs/Features/OtherFeature/assets/diagram.svg", "<svg/>")
.CreateEntry("docs/other.txt", "restored other")
.CreateEntry("docs/assets/icon.png", "icon data")
.ToByteArray()) }
});

ExecutionContext.ServiceProvider = new ServiceCollection()
.AddSingleton<IProjectConfigService>(new ProjectConfigService())
.AddSingleton(Mock.Of<IFeaturesService>(features => features.UseRepositoryClients == useRepositoryClients))
.AddSingleton<IRepositoryLocator, RepositoryLocator>()
.BuildServiceProvider();

Expand All @@ -258,7 +281,13 @@ public void RestoreDependencies_HelpMkDocs()
var handler = PackageTypeFactory.GetPackageTypeHandler(package, false);
handler.Should().BeOfType<HelpMkDocsPackageTypeHandler>();

var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = ciRepo }.Uri;
var repositoryPath = useRepositoryClients ? $"{ciRepo}/Cmf.Custom.Help.1.0.0.zip" : ciRepo;
var repo = new UriBuilder { Scheme = Uri.UriSchemeFile, Host = "", Path = repositoryPath }.Uri;
if (useRepositoryClients)
{
ExecutionContext.ServiceProvider.GetRequiredService<IRepositoryLocator>()
.InitializeClientsForRepositories(fileSystem, new[] { repo });
}

handler.RestoreDependencies(new[] { repo });

Expand All @@ -272,10 +301,25 @@ public void RestoreDependencies_HelpMkDocs()
Assert.Equal("<html>getting started</html>", fileSystem.FileInfo.New($"{docs}/getting-started.html").OpenText().ReadToEnd());
Assert.Equal("# Reference", fileSystem.FileInfo.New($"{docs}/reference.md").OpenText().ReadToEnd());

Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md"));
Assert.Equal("<svg/>", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/assets/diagram.svg"));
Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md"));

// Repeated restores refresh the dependency tree while preserving local project sources.
fileSystem.File.WriteAllText($"{docs}/obsolete.md", "stale dependency page");
handler.RestoreDependencies(new[] { repo });
Assert.False(fileSystem.File.Exists($"{docs}/obsolete.md"), "Stale dependency pages should be removed");
Assert.Equal("# Reference", fileSystem.File.ReadAllText($"{docs}/reference.md"));
Assert.Equal("# Local project documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/LocalProject/index.md"));
Assert.Equal("# Feature documentation", fileSystem.File.ReadAllText($"{gitRepo}/docs/Features/OtherFeature/index.md"));

// Verify files outside docs/tenant were not touched or restored
Assert.True(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).Exists, "File outside docs/tenant was removed");
Assert.Equal("original other", fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\other.txt")).OpenText().ReadToEnd());
Assert.False(fileSystem.FileInfo.New(MockUnixSupport.Path($@"{gitRepo}\docs\assets\icon.png")).Exists, "Assets folder should not be restored");
Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/index.html"), "Generated home page should not be restored as a source");
Assert.False(fileSystem.Directory.Exists($"{gitRepo}/docs/search"), "Generated search files should not be restored");
Assert.False(fileSystem.File.Exists($"{gitRepo}/docs/assets/theme.css"), "Generated assets should not be restored");
}
}
}
Loading