Add information about configuration (#39)

* Add
[Configuration](https://github.com/Azure/bicep-refdocs-generator/blob/main/docs/configuration.md)
for information on how to customize the generation process.
* Reorganize some code and fix tests.

Author: anthony-c-martin

README.md

@@ -1,54 +1,14 @@
 # Template reference
 
-This repo contains the code for generating template reference documentation. It uses files from the **generated** folder in [bicep-types-az](https://github.com/Azure/bicep-types-az) as the source files.
+This repo contains the code for generating [Azure template reference documentation](https://learn.microsoft.com/azure/templates/).
 
-## Accessing Generated Files
+## Configuring
 
-Every push to the `main` branch on this repo will trigger the [Generate GitHub Action](https://github.com/Azure/bicep-refdocs-generator/actions/workflows/generate.yml) which will run generation and upload results as an artifact named "generated".
-
-Download this artifact (see [here](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/downloading-workflow-artifacts) for info), and unzip it. This will give you the full generated docs folder structure.
-
-You can also trigger the Generate action to run on demand (see [here](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) for info) to force generation with the most up-to-date copy of [bicep-types-az](https://github.com/Azure/bicep-types-az).
+See [Configuration](./docs/configuration.md) for information on how you can customize the generation process with remarks, code samples, and descriptions.
 
 ## Development
 
-### Debugging
-
-In VSCode, use the "Launch CLI" debug target to start the application in debug mode.
-
-### Running tests
-
-Run `dotnet test` to run the test suite.
-
-### Updating baselines
-
-If a test failure requires updating the baselines, follow the instructions and run the commands supplied in the error message.
-
-If you want to update all of the baselines in one go, run:
-```sh
-./scripts/update_baselines.sh
-```
-
-### Building
-
-Run `dotnet build` to build this project.
-
-## Using the CLI
-
-After building the .NET solution, you can use the CLI by running:
-
-```sh
-./src/TemplateRefGenerator/bin/Debug/net8.0/TemplateRefGenerator
-```
-
-If you run this command without supplying any arguments, you will see a help message giving information on the supported arguments.
-
-Here's an example of how you can run the CLI tool:
-```sh
-src/TemplateRefGenerator/bin/Debug/net8.0/TemplateRefGenerator --source-folder ../bicep-types-az/generated --output-folder ./generated
-```
-
-To get detailed logging, use the `--verbose` flag.
+See [Developer Guide](./docs/dev_guide.md) for a developer guide on how to use this repo.
 
 ## Contributing
 

docs/configuration.md

@@ -0,0 +1,31 @@
+# Configuration
+
+There are various configuration files that can be used to customize the behavior for the generator. This page explains where to find them and how to use them.
+
+The configuration files all have JSON schemas associated with them. Open them with an IDE like VSCode to get real-time validation.
+
+## Samples
+
+This file can be found under [settings/samples/samples.json](../settings/samples/samples.json). It is used to configure the generation process to include links to external code samples for different resource types. The schema is available [here](../settings/samples.schema.json).
+
+`samples.json` is not manually maintained. It can be updated by running [scripts/UpdateSamples.ps1](../scripts/UpdateSamples.ps1).
+
+## Config
+
+This file can be found under [settings/config/config.json](../settings/config/config.json), and can be used to configure the generation process. The schema is available [here](../settings/config.schema.json).
+
+`config.json` contains central config for:
+* `TocTitleMapping`: used to generate custom page titles for different resource provider namespaces.
+* `ExcludedProviders`: a list of provider namespaces that should be excluded from docs generation.
+
+## Remarks
+
+These set of files can be found under [settings/remarks/<provider_namespace>/remarks.json](../settings/remarks/<provider_namespace>/remarks.json), and can be used to add customizations to different doc pages. The schema is available [here](../settings/remarks.schema.json).
+
+For example, [remarks/microsoft.resources/remarks.json](../settings/remarks/microsoft.resources/remarks.json) can be used to customize documents for the Microsoft.Resources provider namespace.
+
+`remarks.json` contains the following configuration options:
+* `DeploymentRemarks`: Can be used to add custom markdown with information on deploying a particular resource type. For example, explaining some of the quirks.
+* `ResourceRemarks`: Can be used to add custom remarks in markdown format about a particular resource type. See [here](https://github.com/Azure/bicep-refdocs-generator/blob/016143aa9375ba0ce62255fed1fad8905cfe75bf/src/TemplateRefGenerator.Tests/Files/markdown/microsoft.keyvault/2023-07-01/vaults.md?plain=1#L29-L35) for an example of what the customized output looks like.
+* `PropertyRemarks`: Can be used to replace the description markdown for a particular resource type property.
+* `BicepSamples`: A list of `.bicep` files that will be added as samples to documentation. See [here](https://github.com/Azure/bicep-refdocs-generator/blob/016143aa9375ba0ce62255fed1fad8905cfe75bf/src/TemplateRefGenerator.Tests/Files/markdown/microsoft.resources/2024-07-01/resourcegroups.md?plain=1#L61-L75) for an example of what the customized looks like.

docs/dev_guide.md

@@ -0,0 +1,49 @@
+# Developer Guide
+
+## Accessing Generated Files
+
+Every push to the `main` branch on this repo will trigger the [Generate GitHub Action](https://github.com/Azure/bicep-refdocs-generator/actions/workflows/generate.yml) which will run generation and upload results as an artifact named "generated".
+
+Download this artifact (see [here](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/downloading-workflow-artifacts) for info), and unzip it. This will give you the full generated docs folder structure.
+
+You can also trigger the Generate action to run on demand (see [here](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) for info) to force generation with the most up-to-date copy of [bicep-types-az](https://github.com/Azure/bicep-types-az).
+
+## Development
+
+### Debugging
+
+In VSCode, use the "Launch CLI" debug target to start the application in debug mode.
+
+### Running tests
+
+Run `dotnet test` to run the test suite.
+
+### Updating baselines
+
+If a test failure requires updating the baselines, follow the instructions and run the commands supplied in the error message.
+
+If you want to update all of the baselines in one go, run:
+```sh
+./scripts/update_baselines.sh
+```
+
+### Building
+
+Run `dotnet build` to build this project.
+
+## Using the CLI
+
+After building the .NET solution, you can use the CLI by running:
+
+```sh
+./src/TemplateRefGenerator/bin/Debug/net8.0/TemplateRefGenerator
+```
+
+If you run this command without supplying any arguments, you will see a help message giving information on the supported arguments.
+
+Here's an example of how you can run the CLI tool:
+```sh
+src/TemplateRefGenerator/bin/Debug/net8.0/TemplateRefGenerator --source-folder ../bicep-types-az/generated --output-folder ./generated
+```
+
+To get detailed logging, use the `--verbose` flag.

scripts/GetQuickstartLinks.ps1 renamed to scripts/UpdateSamples.ps1

@@ -5,7 +5,7 @@ Param (
 $ErrorActionPreference = "Stop"
 
 $QuickStartsRepoPath = Resolve-Path $QuickStartsRepoPath
-$OutputPath = Join-Path $PSScriptRoot "../src/TemplateRefGenerator/Files/samples/samples.json"
+$OutputPath = Join-Path $PSScriptRoot "../settings/samples/samples.json"
 
 function GetResourceTypes {
     param([PSCustomObject] $template)
@@ -49,7 +49,7 @@ foreach ($metadataPath in $metadataPaths) {
 }
 
 $samples = [ordered]@{
-    "`$schema" = "../samples.schema.json";
+    "`$schema" = "../schemas/samples.schema.json";
     QuickstartLinks = $quickstartLinks;
 }
 

src/TemplateRefGenerator/Files/config/config.json renamed to settings/config/config.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../config.schema.json",
+  "$schema": "../schemas/config.schema.json",
   "TocTitleMapping": {
     "microsoft.aad": "AAD",
     "microsoft.aadiam": "Aadiam",

src/TemplateRefGenerator/Files/remarks/microsoft.alertsmanagement/remarks.json renamed to settings/remarks/microsoft.alertsmanagement/remarks.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../remarks.schema.json",
+  "$schema": "../../schemas/remarks.schema.json",
   "ResourceRemarks": [
     {
       "ResourceTypes": [

src/TemplateRefGenerator/Files/remarks/microsoft.authorization/remarks.json renamed to settings/remarks/microsoft.authorization/remarks.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../remarks.schema.json",
+  "$schema": "../../schemas/remarks.schema.json",
   "ResourceRemarks": [
     {
       "ResourceTypes": [

src/TemplateRefGenerator/Files/remarks/microsoft.azureactivedirectory/remarks.json renamed to settings/remarks/microsoft.azureactivedirectory/remarks.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../remarks.schema.json",
+  "$schema": "../../schemas/remarks.schema.json",
   "ResourceRemarks": [
     {
       "ResourceTypes": [

src/TemplateRefGenerator/Files/remarks/microsoft.containerservice/remarks.json renamed to settings/remarks/microsoft.containerservice/remarks.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../remarks.schema.json",
+  "$schema": "../../schemas/remarks.schema.json",
   "ResourceRemarks": [
     {
       "ResourceTypes": [

src/TemplateRefGenerator/Files/remarks/microsoft.dbformysql/remarks.json renamed to settings/remarks/microsoft.dbformysql/remarks.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../remarks.schema.json",
+  "$schema": "../../schemas/remarks.schema.json",
   "ResourceRemarks": [
     {
       "ResourceTypes": [