Init with files from fuse-open/docs

Initialize README.md, LICENSE.txt, and generator
from https://github.com/fuse-open/docs

LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2018, Fusetools AS.
+All rights reserved.
+
+Redistribution and use in source and "compiled" forms (SGML, HTML, PDF,
+PostScript, RTF and so forth), with or without modification, are permitted
+provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in compiled form (transformed to other DTDs, converted to
+   PDF, PostScript, RTF and other formats) must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,11 @@
+# Azure DevOps HOL
+
+This is the source code for Azure DevOps HOL by taking an example of a documentation project.
+
+The documentation can be hosted on any HTML repositories including your GitHub Pages, from the *gh-pages* branch.
+
+## Running locally
+
+1. Run `dotnet run -p generator/src/generator.csproj -- . "http://localhost:8000/" _site` to build the HTML files.
+2. Run `python3 -m http.server 8000 --directory _site/` (or whatever your favorite static http server is) to serve the website at port 8000.
+3. Open `http://localhost/:8000` in your web browser to view the result.

generator/.gitignore

@@ -0,0 +1,2 @@
+/src/bin/
+/src/obj/

generator/generator.sln

@@ -0,0 +1,34 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio 15
+VisualStudioVersion = 15.0.26124.0
+MinimumVisualStudioVersion = 15.0.26124.0
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "generator", "src\generator.csproj", "{C7938487-87B4-4F3A-A674-E29E1A211706}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Debug|x64 = Debug|x64
+		Debug|x86 = Debug|x86
+		Release|Any CPU = Release|Any CPU
+		Release|x64 = Release|x64
+		Release|x86 = Release|x86
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|x64.ActiveCfg = Debug|x64
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|x64.Build.0 = Debug|x64
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|x86.ActiveCfg = Debug|x86
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Debug|x86.Build.0 = Debug|x86
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|x64.ActiveCfg = Release|x64
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|x64.Build.0 = Release|x64
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|x86.ActiveCfg = Release|x86
+		{C7938487-87B4-4F3A-A674-E29E1A211706}.Release|x86.Build.0 = Release|x86
+	EndGlobalSection
+EndGlobal

generator/global.json

@@ -0,0 +1,5 @@
+{
+  "sdk": {
+    "version": "2.1.102"
+  }
+}

generator/src/BuilderSettings.cs

@@ -0,0 +1,20 @@
+using System;
+
+namespace Builder
+{
+    public class BuilderSettings
+    {
+        public string RootPath { get; }
+        public string OutputPath { get; }
+        public bool GenerateReport { get; }
+        public string BaseUrl { get; }
+
+        public BuilderSettings(string rootPath, string outputPath, bool generateReport, string baseUrl)
+        {
+            RootPath = rootPath;
+            OutputPath = outputPath;
+            GenerateReport = generateReport;
+            BaseUrl = baseUrl;
+        }
+    }
+}

generator/src/DocBuilder.cs

@@ -0,0 +1,74 @@
+using System.Threading.Tasks;
+using Builder.Services;
+using Microsoft.Extensions.Logging;
+
+namespace Builder
+{
+    public class DocBuilder
+    {
+        private readonly BuilderSettings _settings;
+        private readonly ReferenceMap _referenceMap;
+        private readonly Outline _outline;
+        private readonly ApiDocuments _apiDocuments;
+        private readonly ArticleRenderer _articleRenderer;
+        private readonly ApiDocumentRenderer _apiDocumentRenderer;
+        private readonly ApiIndexRenderer _apiIndexRenderer;
+        private readonly OutputPath _outputPath;
+        private readonly MarkdownFormatter _markdownFormatter;
+        private readonly ReportGenerator _reportGenerator;
+        private readonly ILogger<DocBuilder> _logger;
+
+        public DocBuilder(BuilderSettings settings,
+                          ReferenceMap referenceMap,
+                          Outline outline,
+                          ApiDocuments apiDocuments,
+                          ArticleRenderer articleRenderer,
+                          ApiDocumentRenderer apiDocumentRenderer,
+                          ApiIndexRenderer apiIndexRenderer,
+                          OutputPath outputPath,
+                          MarkdownFormatter markdownFormatter,
+                          ReportGenerator reportGenerator,
+                          ILogger<DocBuilder> logger)
+        {
+            _settings = settings;
+            _referenceMap = referenceMap;
+            _outline = outline;
+            _apiDocuments = apiDocuments;
+            _articleRenderer = articleRenderer;
+            _apiDocumentRenderer = apiDocumentRenderer;
+            _apiIndexRenderer = apiIndexRenderer;
+            _outputPath = outputPath;
+            _markdownFormatter = markdownFormatter;
+            _reportGenerator = reportGenerator;
+            _logger = logger;
+        }
+
+        public async Task GenerateAsync()
+        {
+            _logger.LogInformation($"Starting generation of docs from root path {_settings.RootPath}");
+
+            // Prepare rendering by parsing meta data files and loading API JSON payloads
+            var apiDocumentsTask = _apiDocuments.ReadAsync();
+            await Task.WhenAll(_referenceMap.ParseAsync(),
+                               _outline.GenerateAsync(),
+                               _apiIndexRenderer.LoadIndiciesAsync(),
+                               apiDocumentsTask);
+            var apiDocuments = await apiDocumentsTask;
+
+            // Render documentation to disk
+            await Task.WhenAll(_articleRenderer.RenderAsync(),
+                               _apiDocumentRenderer.RenderAsync(apiDocuments));
+
+            // Render all markdown fragments that have been queued up after rendering
+            // and run a post processor path on the output files for any files that have
+            // post processing queued up.
+            await _markdownFormatter.PerformDeferredRenderingAsync();
+            await _outputPath.ApplyContentPostProcessingAsync();
+
+            if (_settings.GenerateReport)
+            {
+                _reportGenerator.Build();
+            }
+        }
+    }
+}

generator/src/Models/ApiDocumentQualityReport.cs

@@ -0,0 +1,18 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiDocumentQualityReport
+    {
+        public ApiReferenceDocument Document { get; }
+        public int NumberOfCommentLines { get; }
+        public Dictionary<string, int> TableOfContentsQuality { get; }
+
+        public ApiDocumentQualityReport(ApiReferenceDocument document, int numberOfCommentLines, Dictionary<string, int> tableOfContentsQuality)
+        {
+            Document = document;
+            NumberOfCommentLines = numberOfCommentLines;
+            TableOfContentsQuality = tableOfContentsQuality;
+        }
+    }
+}

generator/src/Models/ApiReferenceAttribute.cs

@@ -0,0 +1,12 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceAttribute
+    {
+        public ApiReferenceId Id { get; set; }
+        public ApiReferenceUri Uri { get; set; }
+        public ApiReferenceTitle Titles { get; set; }
+        public List<string> Parameters { get; set; } = new List<string>();
+    }
+}

generator/src/Models/ApiReferenceBase.cs

@@ -0,0 +1,10 @@
+namespace Builder.Models
+{
+    public class ApiReferenceBase
+    {
+        public ApiReferenceId Id { get; set; }
+        public ApiReferenceUri Uri { get; set; }
+        public ApiReferenceTitle Titles { get; set; }
+        public ApiReferenceComment Comment { get; set; }
+    }
+}

generator/src/Models/ApiReferenceComment.cs

@@ -0,0 +1,50 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceComment
+    {
+        public string Brief { get; set; }
+        public string Full { get; set; }
+        public string Remarks { get; set; }
+        public string Examples { get; set; }
+        public string Ux { get; set; }
+        public ApiReferenceCommentAttributes Attributes { get; set; }
+
+        public class ApiReferenceCommentAttributes
+        {
+            public bool Advanced { get; set; }
+            public string ScriptModule { get; set; }
+            public ApiReferenceCommentAttributeScriptMethod ScriptMethod { get; set; }
+            public string ScriptProperty { get; set; }
+            public string ScriptEvent { get; set; }
+            public ApiReferenceCommentAttributeReturns Returns { get; set; }
+            public bool Published { get; set; }
+            public string Topic { get; set; }
+            public List<ApiReferenceCommentAttributeParameter> Parameters { get; set; } = new List<ApiReferenceCommentAttributeParameter>();
+            public List<string> SeeAlso { get; set; } = new List<string>();
+            public bool Deprecated { get; set; }
+            public bool Experimental { get; set; }
+            public bool Hidden { get; set; }
+        }
+
+        public class ApiReferenceCommentAttributeScriptMethod
+        {
+            public string Name { get; set; }
+            public List<string> Parameters { get; set; } = new List<string>();
+        }
+
+        public class ApiReferenceCommentAttributeReturns
+        {
+            public string TypeHint { get; set; }
+            public string Text { get; set; }
+        }
+
+        public class ApiReferenceCommentAttributeParameter
+        {
+            public string Name { get; set; }
+            public string TypeHint { get; set; }
+            public string Description { get; set; }
+        }
+    }
+}

generator/src/Models/ApiReferenceDocument.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceDocument : IApiJsonDocument
+    { 
+        public ApiReferenceEntity Entity { get; set; }
+        public Dictionary<string, List<ApiReferenceTocSection>> TableOfContents { get; set; } = new Dictionary<string, List<ApiReferenceTocSection>>();
+        public DateTime SourceFileLastModifiedAt { get; set; } = DateTime.UtcNow;
+    }
+}

generator/src/Models/ApiReferenceEntity.cs

@@ -0,0 +1,21 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceEntity
+    {
+        public ApiReferenceId Id { get; set; }
+        public ApiReferenceUri Uri { get; set; }
+        public ApiReferenceTitle Titles { get; set; }
+        public ApiReferenceComment Comment { get; set; }
+        public ApiReferenceLocation Location { get; set; }
+        public ApiReferenceBase Base { get; set; }
+        public ApiReferenceInheritance Inheritance { get; set; }
+        public List<ApiReferenceParameter> Parameters { get; set; } = new List<ApiReferenceParameter>();
+        public ApiReferenceReturns Returns { get; set; }
+        public List<ApiReferenceInterface> ImplementedInterfaces { get; set; } = new List<ApiReferenceInterface>();
+        public List<ApiReferenceValue> Values { get; set; } = new List<ApiReferenceValue>();
+        public ApiReferenceFlags Flags { get; set; }
+        public List<ApiReferenceAttribute> Attributes { get; set; } = new List<ApiReferenceAttribute>();
+    }
+}

generator/src/Models/ApiReferenceFlags.cs

@@ -0,0 +1,9 @@
+namespace Builder.Models
+{
+    public class ApiReferenceFlags
+    {
+        public bool UxContent { get; set; }
+        public bool UxPrimary { get; set; }
+        public bool UxComponents { get; set; }
+    }
+}

generator/src/Models/ApiReferenceId.cs

@@ -0,0 +1,12 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceId
+    {
+        public string Id { get; set; }
+        public string ParentId { get; set; }
+        public string Type { get; set; }
+        public List<string> Modifiers { get; set; } = new List<string>();
+    }
+}

generator/src/Models/ApiReferenceIndex.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceIndex : IApiJsonDocument
+    {
+        public ApiReferenceEntity Root { get; set; }
+        public List<ApiReferenceTocItem> Descendants { get; set; } = new List<ApiReferenceTocItem>();
+        public DateTime SourceFileLastModifiedAt { get; set; } = DateTime.UtcNow;
+    }
+}

generator/src/Models/ApiReferenceInheritance.cs

@@ -0,0 +1,18 @@
+using System.Collections.Generic;
+
+namespace Builder.Models
+{
+    public class ApiReferenceInheritance
+    {
+        public ApiReferenceInheritanceNode Root { get; set; }
+
+        public class ApiReferenceInheritanceNode
+        {
+            public string Uri { get; set; }
+            public string Title { get; set; }
+            public List<ApiReferenceInheritanceNode> Children { get; set; } = new List<ApiReferenceInheritanceNode>();
+            public bool IsAncestor { get; set; }
+            public bool IsCurrent { get; set; }
+        }
+    }
+}

generator/src/Models/ApiReferenceInterface.cs

@@ -0,0 +1,10 @@
+namespace Builder.Models
+{
+    public class ApiReferenceInterface
+    {
+        public ApiReferenceId Id { get; set; }
+        public ApiReferenceUri Uri { get; set; }
+        public ApiReferenceTitle Titles { get; set; }
+        public ApiReferenceComment Comment { get; set; }
+    }
+}

generator/src/Models/ApiReferenceLocation.cs

@@ -0,0 +1,10 @@
+namespace Builder.Models
+{
+    public class ApiReferenceLocation
+    {
+        public string NamespaceTitle { get; set; }
+        public string NamespaceUri { get; set; }
+        public string PackageName { get; set; }
+        public string PackageVersion { get; set; }
+    }
+}