Skip to content

Commit de03ece

Browse files
kamil-mrzyglodkamil-mrzyglod
committed
Added possibility to define examples
1 parent c3ff330 commit de03ece

File tree

8 files changed

+176
-110
lines changed

8 files changed

+176
-110
lines changed

‎Bicep.Docs.Tests/BasicTests.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@ public class BasicTests
55
[Test]
66
public void Basic_WhenBicepFileIsProvided_DocumentationShouldBeGenerated()
77
{
8-
Program.Main(["templates/basic.bicep"]);
8+
Program.Main(["--template", "templates/basic.bicep"]);
99
}
1010
}

‎Bicep.Docs.Tests/Bicep.Docs.Tests.csproj‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,14 @@
2121
<ProjectReference Include="..\Bicep.Docs\Bicep.Docs.csproj" />
2222
</ItemGroup>
2323

24-
<ItemGroup>
25-
<Folder Include="templates/" />
26-
</ItemGroup>
27-
2824
<ItemGroup>
2925
<Content Include="templates\**\*.*">
3026
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
3127
</Content>
3228
</ItemGroup>
3329

30+
<ItemGroup>
31+
<None Remove="templates/examples/example1.bicep" />
32+
</ItemGroup>
33+
3434
</Project>

‎Bicep.Docs.Tests/templates/basic.bicep‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
metadata BicepDocs = {
2+
examplesDirectory: 'templates/examples'
3+
}
4+
15
@description('Name of the Azure Container Registry')
26
param parAcrName string
37

‎Bicep.Docs.Tests/templates/examples/example1.bicep‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
param parLocation string = 'polandcentral'
2+
3+
module basic '../basic.bicep' = {
4+
name: 'basic'
5+
params: {
6+
parAcrName: 'bicepdocsacr'
7+
parSqlAdminLogin: 'bicepdocsadmin'
8+
parSqlName: 'bicepdocssql'
9+
parLocation: parLocation
10+
}
11+
}

‎Bicep.Docs/Bicep.Docs.csproj‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,8 @@
88
<PublishSingleFile>true</PublishSingleFile>
99
</PropertyGroup>
1010

11+
<ItemGroup>
12+
<PackageReference Include="CommandLineParser" Version="2.9.1" />
13+
</ItemGroup>
14+
1115
</Project>

‎Bicep.Docs/CommandLineOptions.cs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
using CommandLine;
2+
3+
namespace Bicep.Docs;
4+
5+
internal class CommandLineOptions
6+
{
7+
[Option('t', "template", Required = true, HelpText = "The path to the Bicep template file.")]
8+
public required string TemplatePath { get; set; }
9+
}

‎Bicep.Docs/Program.cs‎

Lines changed: 89 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,108 @@
11
using System.Text;
22
using System.Text.Json;
33
using System.Text.Json.Serialization;
4+
using CommandLine;
45

56
namespace Bicep.Docs;
67

78
public class Program
89
{
910
public static void Main(string[] args)
1011
{
11-
var templatePath = args[0];
12-
13-
if (File.Exists(templatePath))
14-
{
15-
var file = new FileInfo(templatePath);
16-
var rawTemplate = BicepCompiler.Compile(file, CancellationToken.None);
17-
18-
#if DEBUG
19-
Console.WriteLine(rawTemplate);
20-
#endif
21-
22-
var parameters = JsonSerializer.Deserialize<TemplateSchema>(rawTemplate!);
23-
24-
var sb = new StringBuilder();
25-
sb.AppendLine($"# {file.Name}");
26-
27-
if (parameters?.Parameters != null)
12+
Parser.Default.ParseArguments<CommandLineOptions>(args)
13+
.WithParsed(o =>
2814
{
29-
sb.AppendLine("## Parameters");
30-
sb.AppendLine("| Name | Description | Type | Default value | Required? | Allowed values |");
31-
sb.AppendLine("|------|-------------|------|---------------|-----------|----------------|");
32-
33-
foreach (var (name, parameter) in parameters.Parameters)
15+
if (File.Exists(o.TemplatePath))
3416
{
35-
var defaultValue = parameter.DefaultValue != null ? $"`{parameter.DefaultValue}`" : "N/A";
36-
var isRequired = defaultValue == "N/A" ? "Yes" : "No";
37-
var allowedValues = parameter.AllowedValues != null ? $"`{string.Join($" / ", parameter.AllowedValues)}`" : "N/A";
38-
var description = parameter.Metadata?["description"] ?? "N/A";
17+
var file = new FileInfo(o.TemplatePath);
18+
var rawTemplate = BicepCompiler.Compile(file, CancellationToken.None);
3919

40-
sb.AppendLine($"| {name} | {description} | {parameter.Type} | {defaultValue} | {isRequired} | {allowedValues} |");
41-
}
42-
}
43-
44-
if (parameters?.Resources != null)
45-
{
46-
sb.AppendLine("## Resources");
47-
sb.AppendLine("| Type | API Version | Name |");
48-
sb.AppendLine("|------|-------------|------|");
20+
#if DEBUG
21+
Console.WriteLine(rawTemplate);
22+
#endif
4923

50-
foreach (var resource in parameters.Resources)
51-
{
52-
sb.AppendLine($"| {resource.Type} | {resource.ApiVersion} | `{resource.Name}` |");
24+
var parameters = JsonSerializer.Deserialize<TemplateSchema>(rawTemplate!);
25+
26+
var sb = new StringBuilder();
27+
sb.AppendLine($"# {file.Name}");
28+
29+
if (parameters?.Parameters != null)
30+
{
31+
sb.AppendLine("## Parameters");
32+
sb.AppendLine("| Name | Description | Type | Default value | Required? | Allowed values |");
33+
sb.AppendLine("|------|-------------|------|---------------|-----------|----------------|");
34+
35+
foreach (var (name, parameter) in parameters.Parameters)
36+
{
37+
var defaultValue = parameter.DefaultValue != null ? $"`{parameter.DefaultValue}`" : "N/A";
38+
var isRequired = defaultValue == "N/A" ? "Yes" : "No";
39+
var allowedValues = parameter.AllowedValues != null ? $"`{string.Join($" / ", parameter.AllowedValues)}`" : "N/A";
40+
var description = parameter.Metadata?["description"] ?? "N/A";
41+
42+
sb.AppendLine($"| {name} | {description} | {parameter.Type} | {defaultValue} | {isRequired} | {allowedValues} |");
43+
}
44+
}
45+
46+
if (parameters?.Resources != null)
47+
{
48+
sb.AppendLine("## Resources");
49+
sb.AppendLine("| Type | API Version | Name |");
50+
sb.AppendLine("|------|-------------|------|");
51+
52+
foreach (var resource in parameters.Resources)
53+
{
54+
sb.AppendLine($"| {resource.Type} | {resource.ApiVersion} | `{resource.Name}` |");
55+
}
56+
}
57+
58+
if (parameters?.Outputs != null)
59+
{
60+
sb.AppendLine("## Outputs");
61+
sb.AppendLine("| Name | Type | Value |");
62+
sb.AppendLine("|------|------|-------|");
63+
64+
foreach (var (name, output) in parameters.Outputs)
65+
{
66+
sb.AppendLine($"| {name} | {output.Type} | `{output.Value}` |");
67+
}
68+
}
69+
70+
if(parameters?.Metadata != null)
71+
{
72+
if(parameters.Metadata.TryGetValue("BicepDocs", out IDictionary<string, string>? docsMetadata))
73+
{
74+
if(docsMetadata.TryGetValue("examplesDirectory", out string? examplesDirectory))
75+
{
76+
if(Directory.Exists(examplesDirectory) == false)
77+
{
78+
throw new DirectoryNotFoundException($"Directory not found: {examplesDirectory}");
79+
}
80+
81+
sb.AppendLine("## Examples");
82+
83+
var examples = Directory.GetFiles(examplesDirectory, "*.bicep", SearchOption.AllDirectories);
84+
foreach (var example in examples)
85+
{
86+
var exampleFile = new FileInfo(example);
87+
var exampleName = exampleFile.Name.Replace(exampleFile.Extension, string.Empty);
88+
var exampleContent = File.ReadAllText(example);
89+
90+
sb.AppendLine($"### {exampleName}");
91+
sb.AppendLine("```bicep");
92+
sb.AppendLine(exampleContent);
93+
sb.AppendLine("```");
94+
}
95+
}
96+
}
97+
}
98+
99+
var result = sb.ToString();
100+
File.WriteAllText("documentation.md", result);
53101
}
54-
}
55-
56-
if (parameters?.Outputs != null)
57-
{
58-
sb.AppendLine("## Outputs");
59-
sb.AppendLine("| Name | Type | Value |");
60-
sb.AppendLine("|------|------|-------|");
61-
62-
foreach (var (name, output) in parameters.Outputs)
102+
else
63103
{
64-
sb.AppendLine($"| {name} | {output.Type} | `{output.Value}` |");
104+
throw new FileNotFoundException($"File not found: {o.TemplatePath}");
65105
}
66-
}
67-
68-
var result = sb.ToString();
69-
File.WriteAllText("documentation.md", result);
70-
}
71-
else
72-
{
73-
throw new FileNotFoundException($"File not found: {templatePath}");
74-
}
106+
});
75107
}
76-
}
77-
78-
internal class TemplateSchema
79-
{
80-
[JsonPropertyName("parameters")]
81-
public IDictionary<string, TemplateParameter>? Parameters { get; set; }
82-
83-
[JsonPropertyName("resources")]
84-
public Resource[]? Resources { get; set; }
85-
86-
[JsonPropertyName("outputs")]
87-
public IDictionary<string, Output>? Outputs { get; set; }
88-
}
89-
90-
internal class TemplateParameter
91-
{
92-
[JsonPropertyName("type")]
93-
public string Type { get; set; } = null!;
94-
95-
[JsonPropertyName("defaultValue")]
96-
public string? DefaultValue { get; set; }
97-
98-
[JsonPropertyName("allowedValues")]
99-
public string[]? AllowedValues { get; set; }
100-
101-
[JsonPropertyName("metadata")]
102-
public IDictionary<string, string>? Metadata { get; set; }
103-
}
104-
105-
internal class Resource
106-
{
107-
[JsonPropertyName("type")]
108-
public string Type { get; set; } = null!;
109-
110-
[JsonPropertyName("apiVersion")]
111-
public string ApiVersion { get; set; } = null!;
112-
113-
[JsonPropertyName("name")]
114-
public string Name { get; set; } = null!;
115-
}
116-
117-
internal class Output
118-
{
119-
[JsonPropertyName("type")]
120-
public string Type { get; set; } = null!;
121-
122-
[JsonPropertyName("value")]
123-
public string Value { get; set; } = null!;
124108
}

‎Bicep.Docs/TemplateSchema.cs‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
using System.Text.Json.Serialization;
2+
3+
namespace Bicep.Docs;
4+
5+
internal class TemplateSchema
6+
{
7+
[JsonPropertyName("parameters")]
8+
public IDictionary<string, TemplateParameter>? Parameters { get; set; }
9+
10+
[JsonPropertyName("resources")]
11+
public Resource[]? Resources { get; set; }
12+
13+
[JsonPropertyName("outputs")]
14+
public IDictionary<string, Output>? Outputs { get; set; }
15+
16+
[JsonPropertyName("metadata")]
17+
public IDictionary<string, IDictionary<string, string>>? Metadata { get; set; }
18+
}
19+
20+
internal class TemplateParameter
21+
{
22+
[JsonPropertyName("type")]
23+
public string Type { get; set; } = null!;
24+
25+
[JsonPropertyName("defaultValue")]
26+
public string? DefaultValue { get; set; }
27+
28+
[JsonPropertyName("allowedValues")]
29+
public string[]? AllowedValues { get; set; }
30+
31+
[JsonPropertyName("metadata")]
32+
public IDictionary<string, string>? Metadata { get; set; }
33+
}
34+
35+
internal class Resource
36+
{
37+
[JsonPropertyName("type")]
38+
public string Type { get; set; } = null!;
39+
40+
[JsonPropertyName("apiVersion")]
41+
public string ApiVersion { get; set; } = null!;
42+
43+
[JsonPropertyName("name")]
44+
public string Name { get; set; } = null!;
45+
}
46+
47+
internal class Output
48+
{
49+
[JsonPropertyName("type")]
50+
public string Type { get; set; } = null!;
51+
52+
[JsonPropertyName("value")]
53+
public string Value { get; set; } = null!;
54+
}

0 commit comments

Comments
 (0)