Experimental documentation generation tool

Simulation.sln

@@ -57,6 +57,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Library2", "src\Simulation\
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "UnitTests", "src\Simulation\Simulators.Tests\TestProjects\UnitTests\UnitTests.csproj", "{46278108-D247-4EFC-AC34-23D4A676F62F}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Simulation", "Simulation", "{80FAB019-3E68-4094-8218-4855610ACF99}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DocumentationGeneration", "src\Simulation\DocumentationGenerationStep\DocumentationGeneration.csproj", "{D4177102-5553-49D6-851C-E3E3CB3E6C8A}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -389,6 +393,22 @@ Global
 		{46278108-D247-4EFC-AC34-23D4A676F62F}.RelWithDebInfo|Any CPU.Build.0 = Release|Any CPU
 		{46278108-D247-4EFC-AC34-23D4A676F62F}.RelWithDebInfo|x64.ActiveCfg = Release|Any CPU
 		{46278108-D247-4EFC-AC34-23D4A676F62F}.RelWithDebInfo|x64.Build.0 = Release|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Debug|x64.Build.0 = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.MinSizeRel|Any CPU.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.MinSizeRel|Any CPU.Build.0 = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.MinSizeRel|x64.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.MinSizeRel|x64.Build.0 = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Release|x64.ActiveCfg = Release|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.Release|x64.Build.0 = Release|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.RelWithDebInfo|Any CPU.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.RelWithDebInfo|Any CPU.Build.0 = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.RelWithDebInfo|x64.ActiveCfg = Debug|Any CPU
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A}.RelWithDebInfo|x64.Build.0 = Debug|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -416,6 +436,8 @@ Global
 		{7256B986-6705-42FC-9F57-485D72D9DE51} = {09C842CB-930C-4C7D-AD5F-E30DE4A55820}
 		{A85277B3-4E07-4E15-8F0C-07CC855A3BCB} = {09C842CB-930C-4C7D-AD5F-E30DE4A55820}
 		{46278108-D247-4EFC-AC34-23D4A676F62F} = {09C842CB-930C-4C7D-AD5F-E30DE4A55820}
+		{80FAB019-3E68-4094-8218-4855610ACF99} = {99E234BC-997E-4E63-9F5C-3C3977543404}
+		{D4177102-5553-49D6-851C-E3E3CB3E6C8A} = {80FAB019-3E68-4094-8218-4855610ACF99}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {929C0464-86D8-4F70-8835-0A5EAF930821}

build/manifest.ps1

@@ -25,6 +25,7 @@
         ".\src\simulation\Simulators\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Simulation.Common.dll",
         ".\src\simulation\Simulators\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Simulation.QCTraceSimulatorRuntime.dll",
         ".\src\simulation\Simulators\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Simulators.dll",
+        ".\src\simulation\DocumentationGenerationStep\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Experimental.DocumentationGeneration.dll",
         ".\src\Xunit\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Xunit.dll"
     ) | ForEach-Object { Get-Item (Join-Path $PSScriptRoot (Join-Path ".." $_)) };
 } | Write-Output;

build/pack.ps1

@@ -67,6 +67,7 @@ Pack-Dotnet '../src/Simulation/QsharpCore/Microsoft.Quantum.QSharp.Core.csproj'
 Pack-One '../src/Simulation/Simulators/Microsoft.Quantum.Simulators.nuspec'
 Pack-One '../src/Quantum.Development.Kit/Microsoft.Quantum.Development.Kit.nuspec'
 Pack-One '../src/Xunit/Microsoft.Quantum.Xunit.csproj'
+Pack-One '../src/Simulation/DocumentationGenerationStep/DocumentationGeneration.csproj'
 
 if (-not $all_ok) {
     throw "At least one project failed to pack. Check the logs."

src/Simulation/DocumentationGenerationStep/Attributes.qs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.Documentation {
+
+    /// # Summary
+    /// Used to denote the summary for a callable or type declaration.
+    @Attribute()
+    newtype Summary = String;
+
+    /// # Summary
+    /// Used to denote the description of a callable or type declaration.
+    @Attribute()
+    newtype Description = String;
+
+    /// # Summary
+    /// Used to denote remarks about a callable or type declaration.
+    @Attribute()
+    newtype Remarks = String;
+
+    /// # Summary
+    /// Used to denote a related link for a callable or type declaration.
+    /// May appear multiple times.
+    @Attribute()
+    newtype SeeAlso = String;
+
+    /// # Summary
+    /// Used to denote references and citations for a callable or type declaration.
+    @Attribute()
+    newtype References = String;
+
+    /// # Summary
+    /// Used to denote a usage example for a callable or type declaration.
+    /// May appear multiple times.
+    @Attribute()
+    newtype Example = String;
+
+    /// # Summary
+    /// Used to denote a single input to a function or operation.
+    /// May appear once for each input.
+    @Attribute()
+    newtype Input = (
+        Name: String,
+        Summary: String
+    );
+
+    /// # Summary
+    /// Used to denote the output returned from a function or operation.
+    @Attribute()
+    newtype Output = (
+        Name: String,
+        Summary: String
+    );
+
+    /// # Summary
+    /// Used to denote a single type parameter to a function or operation.
+    /// May appear once for each type parameter.
+    @Attribute()
+    newtype TypeParameter = (
+        Name: String,
+        Summary: String
+    );
+
+}

src/Simulation/DocumentationGenerationStep/DocgenStep.cs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+using Microsoft.Quantum.QsCompiler;
+using Microsoft.Quantum.QsCompiler.Experimental;
+using Microsoft.Quantum.QsCompiler.SyntaxTree;
+
+
+namespace Microsoft.Quantum.Documentation
+{
+    public class DocumentationGenerationStep : IRewriteStep
+    {
+        private readonly List<IRewriteStep.Diagnostic> Diagnostics;
+
+        public DocumentationGenerationStep()
+        {
+            this.AssemblyConstants = new Dictionary<string, string>(); // will be populated by the Q# compiler
+            this.Diagnostics = new List<IRewriteStep.Diagnostic>(); // collects diagnostics that will be displayed to the user
+        }
+
+        public string Name => "DocumentationGeneration";
+        public int Priority => 0; // only compared within this dll
+
+        public IDictionary<string, string> AssemblyConstants { get; }
+        public IEnumerable<IRewriteStep.Diagnostic> GeneratedDiagnostics => this.Diagnostics;
+
+        public bool ImplementsPreconditionVerification => true;
+        public bool ImplementsTransformation => true;
+        public bool ImplementsPostconditionVerification => false;
+
+
+        public bool PreconditionVerification(QsCompilation compilation)
+        {
+            var preconditionPassed = true; // nothing to check
+            if (preconditionPassed)
+            {
+                // Diagnostics with severity Info or lower usually won't be displayed to the user.
+                // If the severity is Error or Warning the diagnostic is shown to the user like any other compiler diagnostic,
+                // and if the Source property is set to the absolute path of an existing file,
+                // the user will be directed to the file when double clicking the diagnostics.
+                this.Diagnostics.Add(new IRewriteStep.Diagnostic
+                {
+                    Severity = DiagnosticSeverity.Info,
+                    Message = $"Precondition for {this.Name} was {(preconditionPassed ? "satisfied" : "not satisfied")}.",
+                    Stage = IRewriteStep.Stage.PreconditionVerification
+                });
+
+                foreach (var item in AssemblyConstants)
+                {
+                    this.Diagnostics.Add(new IRewriteStep.Diagnostic
+                    {
+                        Severity = DiagnosticSeverity.Info,
+                        Message = $"Got assembly constant \"{item.Key}\" = \"{item.Value}\".",
+                        Stage = IRewriteStep.Stage.PreconditionVerification
+                    });
+                }
+            }
+            return preconditionPassed;
+        }
+
+        public bool Transformation(QsCompilation compilation, out QsCompilation transformed)
+        {
+            transformed = new ProcessDocComments(
+                AssemblyConstants.TryGetValue("OutputPath", out var path)
+                ? path
+                : null
+            ).OnCompilation(compilation);
+            return true;
+        }
+
+        public bool PostconditionVerification(QsCompilation compilation) =>
+            throw new NotImplementedException();
+    }
+}

src/Simulation/DocumentationGenerationStep/DocumentationGeneration.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.Quantum.Sdk/0.11.2006.403">
+
+  <Import Project="..\Common\AssemblyCommon.props" />
+  <Import Project="..\Common\DebugSymbols.props" />
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+    <AssemblyName>Microsoft.Quantum.Experimental.DocumentationGeneration</AssemblyName>
+  </PropertyGroup>  
+
+  <PropertyGroup>
+    <Authors>Microsoft</Authors>
+    <Description>Experimental documentation generation tool for Q#.</Description>
+    <PackageName>Microsoft.Quantum.Experimental.DocumentationGeneration</PackageName>
+    <PackageReleaseNotes>See: https://docs.microsoft.com/en-us/quantum/relnotes/</PackageReleaseNotes>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/microsoft/qsharp-runtime</PackageProjectUrl>
+    <PackageIconUrl>https://secure.gravatar.com/avatar/bd1f02955b2853ba0a3b1cdc2434e8ec.png</PackageIconUrl>
+    <PackageTags>Quantum Q# Qsharp</PackageTags>
+    <PublishRepositoryUrl>true</PublishRepositoryUrl>
+  </PropertyGroup>  
+
+  <ItemGroup>
+    <Compile Include="..\Common\DelaySign.cs" Link="Properties\DelaySign.cs" />
+  </ItemGroup>
+
+</Project>