Merge work on new documentation generation tool into main.

Build/props/tests.props

@@ -6,12 +6,11 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Quantum.Xunit" Version="0.12.20082515-beta" />
+    <PackageReference Include="Microsoft.Quantum.Xunit" Version="0.12.20102008-beta" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.4.0" />
     <PackageReference Include="xunit" Version="2.4.1" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.4.1" />
     <DotNetCliToolReference Include="dotnet-xunit" Version="2.3.1" />
   </ItemGroup>
 
 </Project>
-

Chemistry/src/Jupyter/BroombridgeMagic.cs

@@ -16,7 +16,7 @@ public class BroombridgeMagic : MagicSymbol
         public BroombridgeMagic()
         {
             this.Name = $"%chemistry.broombridge";
-            this.Documentation = new Documentation() { Summary = "Loads and returns Broombridge electronic structure problem representation from a given .yaml file." };
+            this.Documentation = new Microsoft.Jupyter.Core.Documentation() { Summary = "Loads and returns Broombridge electronic structure problem representation from a given .yaml file." };
             this.Kind = SymbolKind.Magic;
             this.Execute = this.Run;
         }

Chemistry/src/Jupyter/ChemistryEncodeMagic.cs

@@ -17,7 +17,7 @@ public class ChemistryEncodeMagic : MagicSymbol
         public ChemistryEncodeMagic()
         {
             this.Name = $"%chemistry.encode";
-            this.Documentation = new Documentation() { Summary = "Encodes a fermion Hamiltonian to a format consumable by Q#." };
+            this.Documentation = new Microsoft.Jupyter.Core.Documentation() { Summary = "Encodes a fermion Hamiltonian to a format consumable by Q#." };
             this.Kind = SymbolKind.Magic;
             this.Execute = this.Run;
         }

Chemistry/src/Jupyter/FermionHamiltonianMagic.cs

@@ -26,7 +26,7 @@ public class FermionHamiltonianLoadMagic : MagicSymbol
         public FermionHamiltonianLoadMagic()
         {
             this.Name = $"%chemistry.fh.load";
-            this.Documentation = new Documentation() { Summary = "Loads the fermion Hamiltonian for an electronic structure problem. The problem is loaded from a file or passed as an argument." };
+            this.Documentation = new Microsoft.Jupyter.Core.Documentation() { Summary = "Loads the fermion Hamiltonian for an electronic structure problem. The problem is loaded from a file or passed as an argument." };
             this.Kind = SymbolKind.Magic;
             this.Execute = this.Run;
         }
@@ -113,7 +113,10 @@ public class FermionHamiltonianAddTermsMagic : MagicSymbol
         public FermionHamiltonianAddTermsMagic()
         {
             this.Name = $"%chemistry.fh.add_terms";
-            this.Documentation = new Documentation() { Summary = "Adds terms to a fermion Hamiltonian." };
+            this.Documentation = new Microsoft.Jupyter.Core.Documentation
+            {
+                Summary = "Adds terms to a fermion Hamiltonian."
+            };
             this.Kind = SymbolKind.Magic;
             this.Execute = this.Run;
         }

Chemistry/src/Jupyter/WavefunctionMagic.cs

@@ -20,7 +20,7 @@ public class WavefunctionMagic : MagicSymbol
         public WavefunctionMagic()
         {
             this.Name = $"%chemistry.inputstate.load";
-            this.Documentation = new Documentation() { Summary = "Loads Broombridge electronic structure problem and returns selected input state." };
+            this.Documentation = new Microsoft.Jupyter.Core.Documentation() { Summary = "Loads Broombridge electronic structure problem and returns selected input state." };
             this.Kind = SymbolKind.Magic;
             this.Execute = this.Run;
         }

Chemistry/src/Runtime/Runtime.csproj

@@ -1,11 +1,15 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <PropertyGroup>
     <TargetFramework>netstandard2.1</TargetFramework>
     <AssemblyName>Microsoft.Quantum.Chemistry.Runtime</AssemblyName>
     <QsharpDocsGeneration>true</QsharpDocsGeneration>
     <IncludeQsharpCorePackages>false</IncludeQsharpCorePackages>
     <RunQDocGen>True</RunQDocGen>
+    <!-- List the name of the metapackage that users can
+         use to take a dependency on these Q# APIs, rather
+         than the subpackage directly. -->
+    <QsharpDocsPackageId>Microsoft.Quantum.Chemistry</QsharpDocsPackageId>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -36,12 +40,11 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Quantum.Simulators" Version="0.12.20082515-beta" />
+    <PackageReference Include="Microsoft.Quantum.Simulators" Version="0.12.20102008-beta" />
   </ItemGroup>
 
   <ItemGroup>
     <None Include="..\..\..\Build\assets\qdk-nuget-icon.png" Pack="true" Visible="false" PackagePath="" />
   </ItemGroup>
 
 </Project>
-

Chemistry/tests/ChemistryTests/QSharpTests.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <Import Project="..\..\..\Build\props\tests.props" />
 
@@ -12,4 +12,3 @@
   </ItemGroup>
 
 </Project>
-

Chemistry/tests/SystemTests/SystemTests.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <Import Project="..\..\..\Build\props\tests.props" />
 
@@ -39,4 +39,3 @@
   </ItemGroup>
 
 </Project>
-

MachineLearning/src/MachineLearning.csproj

@@ -1,8 +1,9 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
   <PropertyGroup>
     <TargetFramework>netstandard2.1</TargetFramework>
     <AssemblyName>Microsoft.Quantum.MachineLearning</AssemblyName>
     <QsharpDocsGeneration>true</QsharpDocsGeneration>
+    <QsharpDocsPackageId>Microsoft.Quantum.MachineLearning</QsharpDocsPackageId>
     <!--
       Include core packages using project references instead, since they get
       built at the same time as this project.

MachineLearning/src/Types.qs

@@ -10,7 +10,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// Describes a controlled rotation in terms of its target and control
     /// indices, rotation axis, and index into a model parameter vector.
     ///
-    /// # Input
+    /// # Named Items
     /// ## TargetIndex
     /// Index of the target qubit for this controlled rotation.
     /// ## ControlIndices
@@ -50,7 +50,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// parameterized and controlled rotations, an assignment of rotation
     /// angles, and a bias between the two classes recognized by the model.
     ///
-    /// # Input
+    /// # Named Items
     /// ## Structure
     /// The sequence of controlled rotations used to classify inputs.
     /// ## Parameters
@@ -70,7 +70,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// Describes an operation that prepares a given input to a sequential
     /// classifier.
     ///
-    /// # Input
+    /// # Named Items
     /// ## NQubits
     /// The number of qubits on which the encoded input is defined.
     /// ## Prepare
@@ -84,7 +84,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// # Summary
     /// A sample, labeled with a class to which that sample belongs.
     ///
-    /// # Input
+    /// # Named Items
     /// ## Features
     /// A vector of features for the given sample.
     /// ## Label
@@ -152,7 +152,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// The results from having validated a classifier against a set of
     /// samples.
     ///
-    /// # Input
+    /// # Named Items
     /// ## NMisclassifications
     /// The number of misclassifications observed during validation.
     newtype ValidationResults = (
@@ -163,7 +163,7 @@ namespace Microsoft.Quantum.MachineLearning {
     /// # Summary
     /// A collection of options to be used in training quantum classifiers.
     ///
-    /// # Input
+    /// # Named Items
     /// ## LearningRate
     /// The learning rate by which gradients should be rescaled when updating
     /// model parameters during training steps.

MachineLearning/tests/MachineLearningTests.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <Import Project="..\..\Build\props\tests.props" />
 

Numerics/src/Numerics.csproj

@@ -1,9 +1,10 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <PropertyGroup>
     <TargetFramework>netstandard2.1</TargetFramework>
     <AssemblyName>Microsoft.Quantum.Numerics</AssemblyName>
     <QsharpDocsGeneration>true</QsharpDocsGeneration>
+    <QsharpDocsPackageId>Microsoft.Quantum.Numerics</QsharpDocsPackageId>
     <IncludeQsharpCorePackages>false</IncludeQsharpCorePackages>
   </PropertyGroup>
 
@@ -40,9 +41,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Quantum.Simulators" Version="0.12.20082515-beta" />
+    <PackageReference Include="Microsoft.Quantum.Simulators" Version="0.12.20102008-beta" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="All" />
   </ItemGroup>
 
 </Project>
-

Numerics/tests/NumericsTests.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.Quantum.Sdk/0.12.20082515-beta">
+<Project Sdk="Microsoft.Quantum.Sdk/0.12.20102008-beta">
 
   <Import Project="..\..\Build\props\tests.props" />
 

Standard/src/AmplitudeAmplification/AmplitudeAmplification.qs

@@ -185,8 +185,6 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     /// Reflection operator about start state
     /// ## targetStateReflection
     /// Reflection operator about target state
-    /// ## startQubits
-    /// Qubit register
     ///
     /// # Output
     /// An operation that implements amplitude amplification by partial reflections.
@@ -223,8 +221,6 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     /// Unitary oracle $A$ that prepares start state
     /// ## idxFlagQubit
     /// Index to flag qubit
-    /// ## qubits
-    /// Start state register
     ///
     /// # Output
     /// An operation that implements amplitude amplification by oracles that are
@@ -259,12 +255,10 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     /// # Input
     /// ## nIterations
     /// Number of iterations $n$ of amplitude amplification
-    /// ## statePrepOracle
+    /// ## stateOracle
     /// Unitary oracle $A$ that prepares start state
     /// ## idxFlagQubit
     /// Index to flag qubit
-    /// ## qubits
-    /// Start state register
     ///
     /// # Output
     /// An operation that implements the standard amplitude amplification quantum algorithm

Standard/src/AmplitudeAmplification/Types.qs

@@ -6,10 +6,15 @@ namespace Microsoft.Quantum.AmplitudeAmplification {
     /// # Summary
     /// Phases for a sequence of partial reflections in amplitude amplification.
     ///
-    /// # Remarks
-    /// The first parameter is an array of phases for reflection about the
-    /// start state. The second parameter is an array of phases for reflection
+    /// # Named Items
+    /// ## AboutStart
+    /// An array of phases for reflection about the
+    /// start state.
+    /// ## AboutTarget
+    /// An array of phases for reflection
     /// about the target state.
+    ///
+    /// # Remarks
     /// Both arrays must be of equal length. Note that in many cases, the first phase about the start state and last phase about the target state introduces a global phase shift and may be set to $0$.
     newtype ReflectionPhases = (
         AboutStart: Double[],

Standard/src/Arithmetic/ApplyDual.qs

@@ -37,7 +37,7 @@ namespace Microsoft.Quantum.Arithmetic {
     }
 
     /// # See Also
-    /// - ApplyPhaseLEOperationOnLE
+    /// - Microsoft.Quantum.Canon.ApplyPhaseLEOperationOnLE
     operation ApplyPhaseLEOperationOnLEA (op : (PhaseLittleEndian => Unit is Adj), target : LittleEndian) : Unit
     {
         body (...)
@@ -53,7 +53,7 @@ namespace Microsoft.Quantum.Arithmetic {
 
 
     /// # See Also
-    /// - @"microsoft.quantum.canon.applyphaseleoperationonle"
+    /// - Microsoft.Quantum.Canon.ApplyPhaseLEOperationOnLE
     operation ApplyPhaseLEOperationOnLEC (op : (PhaseLittleEndian => Unit is Ctl), target : LittleEndian) : Unit
     {
         body (...)
@@ -75,7 +75,7 @@ namespace Microsoft.Quantum.Arithmetic {
 
 
     /// # See Also
-    /// - @"microsoft.quantum.canon.applyphaseleoperationonle"
+    /// - Microsoft.Quantum.Canon.ApplyPhaseLEOperationOnLE
     operation ApplyPhaseLEOperationOnLECA (op : (PhaseLittleEndian => Unit is Adj + Ctl), target : LittleEndian) : Unit
     {
         body (...)