Generating Documentation

DocFX - deploying API documentation to SQTechDocs

1. Create a documentation folder in the repository root with the docfx.json and docmetadata files
2. Identify your project ID, which will correspond to the SQTech docs URL/blob storage container.
3. If using NukeExt as a library via a build project file:
   1. Add [DocFXAzurePipelines("{yourprojectid}")] to your Build class
   2. Inherit from the interface ICreateDocFX.
4. Otherwise, if using NukeTool:
   1. Specify “ProjectName” in parameters.json
   2. Run build.cmd --generate-configuration AzurePipelines_docfx
5. Create a new build pipeline to run the generated azure-pipelines.docfx.yml file

Doxygen - deploying API documentation to SQTechDocs

1. Create a documentation folder in the repository with the docmetadata file
2. Identify your project ID, which will correspond to the SQTech docs URL/blob storage container.
3. Add [DoxygenAzurePipelines("{yourprojectid}")] to your Build class.
4. Inherit from the interface ICreateDoxygen.
5. Create a new build pipeline to run the generated azure-pipelines.doxygen.yml file

DocFX/Doxygen - adding last modified date to HTML pages

1. Add a reference to the NuGet package Microsoft.XboxStudios.NukeExt.Documentation.LastModified. For example:

   <ItemGroup Condition="'$(GenerateDocs)' == 'true'">
       <PackageReference Include="Microsoft.XboxStudios.NukeExt.Documentation.LastModified" Version="1.1.1" />
   </ItemGroup>

2. Inherit from ICreateDocFXLastModifiedStamp instead of ICreateDocFX, or ICreateDoxygenLastModifiedStamp instead of ICreateDoxygen.

3. Configure as needed for your project, by overriding properties in the ICreateLastModifiedStamp interface:

   • All files that match the pattern **/*.md in the root documentation directory will be stamped with the last modified date except for api/*.md. To use different files, override the IncludeDocumentationFilePatterns or ExcludeDocumentationFilePatterns properties.

   • Note documentation files must be tracked by git to retrieve the last modified date.

   • By default, the last modified stamp is inserted with a line break at the HTML node //article[contains(@class, 'content wrap')]. To use a different HTML node, override the LastModifiedHtmlNode property.

   • By default, the last modified stamp is appended to the HTML node. To change the placement of the stamp, override the LastModifiedStampPlacement property.

   • To disable the line break, override the InsertLineBreakAfterLastModified property to false.