#19 Migrated project site to CodeMap

.github/workflows/build-and-deploy.yml

@@ -153,17 +153,30 @@ jobs:
         asset_path: ./publish/Mup.${{ steps.package_info.outputs.package_version }}.nupkg
         asset_name: Mup.${{ steps.package_info.outputs.package_version }}.nupkg
         asset_content_type: application/zip
+
+    - name: Prepare Project Site Build
+      shell: pwsh
+      run: |
+        mkdir ./project-site
+        mkdir ./project-site/dev
 
-    - name: Build Project Site
+    - name: Generate Project Site (dev)
       if: github.ref == 'refs/heads/master'
+      working-directory: ./project-site/dev
+      shell: pwsh
+      run: |
+        dotnet run --project ../../Mup.Documentation --configuration Release
+
+    - name: Generate Project Site (Release)
+      if: startsWith(github.ref, 'refs/heads/releases/')
       working-directory: ./project-site
+      shell: pwsh
       run: |
-        npm install
-        npm run release-build
+        dotnet run --project ../Mup.Documentation --configuration Release
     
     - name: Publish Project Site
       uses: peaceiris/[email protected]
       if: github.ref == 'refs/heads/master'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./project-site/build
+        publish_dir: ./project-site

project-site/views/license.scss → Mup.Documentation/Assets/style.css

@@ -1,3 +1,24 @@
+body {
+    min-height: 100vh;
+}
+
+th {
+    white-space: nowrap;
+}
+
+p, th, td, li {
+    text-align: justify;
+}
+
+table.table > thead > tr > th p:last-child, table.table > tbody > tr > td p:last-child {
+    margin-bottom: 0;
+}
+
+pre {
+    padding: 2px 7px;
+    background-color: #F8F8F8;
+}
+
 .license ol {
     counter-reset: item;
     list-style-type: none;

Mup.Documentation/CodeMapHandlebarsTemplateWriter.cs

@@ -0,0 +1,27 @@
+using System;
+using System.Collections.Generic;
+using CodeMap.Handlebars;
+
+namespace Mup.Documentation
+{
+    public class CodeMapHandlebarsTemplateWriter : HandlebarsTemplateWriter
+    {
+        public CodeMapHandlebarsTemplateWriter(IMemberReferenceResolver memberReferenceResolver)
+            : base(memberReferenceResolver)
+        {
+        }
+
+        protected override IReadOnlyDictionary<string, string> GetPartials()
+            => new Dictionary<string, string>(base.GetPartials(), StringComparer.OrdinalIgnoreCase)
+            {
+                ["Layout"] = ReadFromEmbeddedResource(typeof(Program).Assembly, "Mup.Documentation.Partials.Layout.hbs")
+            };
+
+        protected override IReadOnlyDictionary<string, string> GetTemplates()
+            => new Dictionary<string, string>(base.GetTemplates(), StringComparer.OrdinalIgnoreCase)
+            {
+                ["Index"] = ReadFromEmbeddedResource(typeof(Program).Assembly, "Mup.Documentation.Templates.Index.hbs"),
+                ["License"] = ReadFromEmbeddedResource(typeof(Program).Assembly, "Mup.Documentation.Templates.License.hbs")
+            };
+    }
+}

Mup.Documentation/CodeMapMemberReferenceResolver.cs

@@ -0,0 +1,25 @@
+using CodeMap.DeclarationNodes;
+using CodeMap.Handlebars;
+using CodeMap.ReferenceData;
+
+namespace Mup.Documentation
+{
+    public class CodeMapMemberReferenceResolver : IMemberReferenceResolver
+    {
+        private readonly IMemberReferenceResolver _memberReferenceResolver;
+
+        public CodeMapMemberReferenceResolver()
+            => _memberReferenceResolver = new DefaultMemberReferenceResolver(typeof(ParseTreeVisitor).Assembly, "netstandard-1.0");
+
+        public string GetFileName(DeclarationNode declarationNode)
+        {
+            if (declarationNode is AssemblyDeclaration assemblyDeclaration && assemblyDeclaration == typeof(ParseTreeVisitor).Assembly)
+                return "documentation.html";
+            else
+                return _memberReferenceResolver.GetFileName(declarationNode);
+        }
+
+        public string GetUrl(MemberReference memberReference)
+            => _memberReferenceResolver.GetUrl(memberReference);
+    }
+}

Mup.Documentation/FileWriterTemplateWriterDeclarationNodeVisitor.cs

@@ -0,0 +1,18 @@
+using System.IO;
+using CodeMap.DeclarationNodes;
+using CodeMap.Handlebars;
+
+namespace Mup.Documentation
+{
+    public class FileWriterTemplateWriterDeclarationNodeVisitor : TemplateWriterDeclarationNodeVisitor
+    {
+        private readonly IMemberReferenceResolver _memberReferenceResolver;
+
+        public FileWriterTemplateWriterDeclarationNodeVisitor(IMemberReferenceResolver memberReferenceResolver, TemplateWriter templateWriter)
+            : base(templateWriter)
+            => _memberReferenceResolver = memberReferenceResolver;
+
+        protected override TextWriter GetTextWriter(DeclarationNode declarationNode)
+            => new StreamWriter(new FileStream(_memberReferenceResolver.GetFileName(declarationNode), FileMode.Create, FileAccess.Write, FileShare.Read));
+    }
+}

Mup.Documentation/Mup.Documentation.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Include="Assets\favicon.ico" />
+    <EmbeddedResource Include="Assets\logo.png" />
+    <EmbeddedResource Include="Assets\style.css" />
+    <EmbeddedResource Include="Partials\Layout.hbs" />
+    <EmbeddedResource Include="Templates\Index.hbs" />
+    <EmbeddedResource Include="Templates\License.hbs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="CodeMap" Version="1.0.0-beta1" />
+    <PackageReference Include="CodeMap.Handlebars" Version="1.0.0-beta1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Mup\Mup.csproj" />
+  </ItemGroup>
+
+</Project>

Mup.Documentation/MupAssemblyDocumentationAddition.cs

@@ -0,0 +1,77 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using CodeMap.DeclarationNodes;
+using CodeMap.DocumentationElements;
+
+namespace Mup.Documentation
+{
+    public class MupAssemblyDocumentationAddition : AssemblyDocumentationAddition
+    {
+        public override bool CanApply(AssemblyDeclaration assembly)
+            => true;
+
+        public override SummaryDocumentationElement GetSummary(AssemblyDeclaration assembly)
+            => DocumentationElement.Summary(
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text(
+                        assembly
+                            .Attributes
+                            .Single(attribute => attribute.Type == typeof(AssemblyDescriptionAttribute))
+                            .PositionalParameters
+                            .Single()
+                            .Value
+                            .ToString()
+                    )
+                )
+            );
+
+        public override RemarksDocumentationElement GetRemarks(AssemblyDeclaration assembly)
+            => DocumentationElement.Remarks(
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("The library has a few core types that make it work: "),
+                    DocumentationElement.Hyperlink("Mup.IMarkupParser.html", "IMarkupParser"),
+                    DocumentationElement.Text(" "),
+                    DocumentationElement.Hyperlink("Mup.Elements.ParseTreeRootElement.html", "ParseTreeRootElement"),
+                    DocumentationElement.Text(" and "),
+                    DocumentationElement.Hyperlink("Mup.ParseTreeVisitor.html", "ParseTreeVisitor"),
+                    DocumentationElement.Text(".")
+                ),
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("Each parser (currently just Creole) implements the IMarkupParser interface which exposes a number of methods that allow parsing a "),
+                    DocumentationElement.Hyperlink("https://docs.microsoft.com/dotnet/api/system.string?view=netstandard-1.0", "string"),
+                    DocumentationElement.Text(" or text from a "),
+                    DocumentationElement.Hyperlink("https://docs.microsoft.com/dotnet/api/system.io.textreader?view=netstandard-1.0", "TextReader"),
+                    DocumentationElement.Text(". Each parser supports both synchronous and asynchronous models allowing its users to consume the API any way they want.")
+                ),
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("The result of any parse method is ultimately a "),
+                    DocumentationElement.Hyperlink("Mup.Elements.ParseTreeRootElement.html", "ParseTreeRootElement"),
+                    DocumentationElement.Text(". Surprisingly or not, this interface does not expose something like a root node or anything related to what one would expect when seeing the word \"tree\".")
+                ),
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("This is because trees can have different representations. For instance, we can have the usual example where we have a root node which exposes a property containing a number of nodes that are in fact child nodes, each child node also exposes such a property that contains their child nodes and so on. A different representation can be a flat one where the entire tree is stored as a list of elements that mark the beginning and end of each node.")
+                ),
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("Regardless of how we represent a parse tree, we need to be able to traverse it in order to generate a specific output, say HTML. This is where a "),
+                    DocumentationElement.Hyperlink("Mup.ParseTreeVisitor.html", "ParseTreeVisitor"),
+                    DocumentationElement.Text(" comes into play. Any "),
+                    DocumentationElement.Hyperlink("Mup.Elements.ParseTreeRootElement.html", "ParseTreeRootElement"),
+                    DocumentationElement.Text(" exposes methods that accept a "),
+                    DocumentationElement.Hyperlink("Mup.ParseTreeVisitor.html", "ParseTreeVisitor"),
+                    DocumentationElement.Text(", the entire logic for traversing the tree is encapsulated inside itself. Each time a node is being visited, a specific method for that node is called on the visitor. This helps keep the interface clean and completely decouple the language that is being parsed from the desired output format. Any new markup parser will work with existing visitors and any new visitor will work with any existing parser.")
+                ),
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("The one common rule for all parse trees is that they are all traversed in pre-order (see "),
+                    DocumentationElement.Hyperlink("https://en.wikipedia.org/wiki/Tree_traversal", "Tree Traversal (Wikipedia)"),
+                    DocumentationElement.Text(" for more about this topic).")
+                )
+            );
+
+        public override IEnumerable<NamespaceDocumentationAddition> GetNamespaceAdditions(AssemblyDeclaration assembly)
+        {
+            yield return new MupNamespaceDocumentationAddition();
+            yield return new MupElementsNamespaceDocumentationAddition();
+        }
+    }
+}

Mup.Documentation/MupElementsNamespaceDocumentationAddition.cs

@@ -0,0 +1,19 @@
+using System;
+using CodeMap.DeclarationNodes;
+using CodeMap.DocumentationElements;
+
+namespace Mup.Documentation
+{
+    public class MupElementsNamespaceDocumentationAddition : NamespaceDocumentationAddition
+    {
+        public override bool CanApply(NamespaceDeclaration @namespace)
+            => string.Equals("Mup.Elements", @namespace.Name, StringComparison.OrdinalIgnoreCase);
+
+        public override SummaryDocumentationElement GetSummary(NamespaceDeclaration @namespace)
+            => DocumentationElement.Summary(
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("Contains the parse nodes representing a mark-up document.")
+                )
+            );
+    }
+}

Mup.Documentation/MupNamespaceDocumentationAddition.cs

@@ -0,0 +1,19 @@
+using System;
+using CodeMap.DeclarationNodes;
+using CodeMap.DocumentationElements;
+
+namespace Mup.Documentation
+{
+    public class MupNamespaceDocumentationAddition : NamespaceDocumentationAddition
+    {
+        public override bool CanApply(NamespaceDeclaration @namespace)
+            => string.Equals("Mup", @namespace.Name, StringComparison.OrdinalIgnoreCase);
+
+        public override SummaryDocumentationElement GetSummary(NamespaceDeclaration @namespace)
+            => DocumentationElement.Summary(
+                DocumentationElement.Paragraph(
+                    DocumentationElement.Text("Contains the base Mup types and implemented parsers.")
+                )
+            );
+    }
+}

Mup.Documentation/Partials/Layout.hbs

@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
+    <meta http-equiv="Pragma" content="no-cache" />
+    <meta http-equiv="Expires" content="0" />
+    <title>{{title}}</title>
+    <link rel="icon" href="favicon.ico">
+    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous" />
+    <link rel="stylesheet" href="style.css" />
+</head>
+<body class="d-flex flex-column">
+    <div>
+        <div class="d-flex flex-row align-items-center container px-2 pt-2">
+            <h1 class="mt-4 mb-3"><img src="logo.png" alt="logo"> <abbr title="MarkUp Parser">Mup</abbr> <small>Markup for Everyone</small></h1>
+        </div>
+    </div>
+
+    <div class="flex-grow-1 flex-shrink-1">
+        <div class="d-flex flex-column container px-2 pt-2">
+            <div class="mb-3">
+                <ul class="nav nav-pills p-auto">
+                    <li class="nav-item">
+                        {{#if isHomeSelected}}
+                        <a class="nav-link active" aria-current="true" href="index.html">Home</a>
+                        {{else}}
+                        <a class="nav-link" aria-current="false" href="index.html">Home</a>
+                        {{/if}}
+                    </li>
+                    <li class="nav-item">
+                        {{#unless isHomeSelected}}
+                        {{#unless isLicenseSelected}}
+                        <a class="nav-link active" aria-current="true" href="documentation.html">Documentation</a>
+                        {{else}}
+                        <a class="nav-link" aria-current="false" href="documentation.html">Documentation</a>
+                        {{/unless}}
+                        {{else}}
+                        <a class="nav-link" aria-current="false" href="documentation.html">Documentation</a>
+                        {{/unless}}
+                    </li>
+                    <li class="nav-item">
+                        {{#if isLicenseSelected}}
+                        <a class="nav-link active" aria-current="true" href="license.html">License</a>
+                        {{else}}
+                        <a class="nav-link" aria-current="false" href="license.html">License</a>
+                        {{/if}}
+                    </li>
+                    <li class="nav-item"><a class="nav-link" href="https://github.com/Andrei15193/Mup" target="_blank">View on GitHub</a></li>
+                </ul>
+            </div>
+            {{#if node}}
+            {{> Breadcrumbs node}}
+
+            {{> @partial-block node}}
+            {{else}}
+            {{> @partial-block}}
+            {{/if}}
+        </div>
+    </div>
+
+    <div>
+        <div class="d-flex flex-column container px-2">
+            <p class="text-center">Mup Copyright © 2020 Andrei Fangli</p>
+        </div>
+    </div>
+
+    <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
+    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
+</body>
+</html>

Mup.Documentation/Program.cs

@@ -0,0 +1,35 @@
+using System.IO;
+using System.Text.RegularExpressions;
+using CodeMap.DeclarationNodes;
+
+namespace Mup.Documentation
+{
+    internal static class Program
+    {
+        internal static void Main()
+        {
+            var mupAssembly = typeof(ParseTreeVisitor).Assembly;
+            var mupAssemblyDeclration = DeclarationNode.Create(mupAssembly).Apply(new MupAssemblyDocumentationAddition());
+
+            var memberReferenceResolver = new CodeMapMemberReferenceResolver();
+            var templateWriter = new CodeMapHandlebarsTemplateWriter(memberReferenceResolver);
+
+            var declarationNodeVisitor = new FileWriterTemplateWriterDeclarationNodeVisitor(memberReferenceResolver, templateWriter);
+
+            foreach (var assetResourceName in typeof(Program).Assembly.GetManifestResourceNames())
+            {
+                var match = Regex.Match(assetResourceName, @"\.Assets\.(?<assetName>\w+\.\w+)$", RegexOptions.IgnoreCase);
+                if (match.Success)
+                    using (var assetFileStream = new FileStream(match.Groups["assetName"].Value, FileMode.Create, FileAccess.Write, FileShare.Read))
+                    using (var assetResourceStream = typeof(Program).Assembly.GetManifestResourceStream(assetResourceName))
+                        assetResourceStream.CopyTo(assetFileStream);
+            }
+
+            using (var indexPageWriter = new StreamWriter(new FileStream("index.html", FileMode.Create, FileAccess.Write, FileShare.Read)))
+                templateWriter.Write(indexPageWriter, "Index", new { isHomeSelected = true });
+            using (var indexPageWriter = new StreamWriter(new FileStream("license.html", FileMode.Create, FileAccess.Write, FileShare.Read)))
+                templateWriter.Write(indexPageWriter, "License", new { isLicenseSelected = true });
+            mupAssemblyDeclration.Accept(declarationNodeVisitor);
+        }
+    }
+}