Merge pull request #127 from jasonjoh/tags

Tags and Includes

ApiDocs.Console/CommandLineOptions.cs

@@ -95,6 +95,26 @@ class BaseOptions
         [Option("ignore-errors", HelpText="Prevent errors from generating a non-zero return code.")]
         public bool IgnoreErrors { get; set; }
 
+        [Option("parameters", HelpText = "Specify additional page variables that are used by the publishing engine. URL encoded: key=value&key2=value2.")]
+        public string AdditionalPageParameters { get; set; }
+
+        public Dictionary<string,object> PageParameterDict {
+            get
+            {
+                if (string.IsNullOrEmpty(AdditionalPageParameters))
+                    return null;
+
+                var data = new Dictionary<string, object>();
+
+                var parameters = Validation.Http.HttpParser.ParseQueryString(AdditionalPageParameters.ToLower());
+                foreach (var key in parameters.AllKeys)
+                {
+                    data[key] = parameters[key];
+                }
+                return data;
+            }
+        }
+
 #if DEBUG
         [Option("debug", HelpText="Launch the debugger before doing anything interesting")]
         public bool AttachDebugger { get; set; }
@@ -378,9 +398,6 @@ public string[] FilesToPublish {
             set { this.SourceFiles = value.ComponentsJoinedByString(";"); }
         }
 
-        [Option("parameters", HelpText="Specify additional page variables that are used by the publishing engine. URL encoded: key=value&key2=value2.")]
-        public string AdditionalPageParameters { get; set; }
-
         [Option("allow-unsafe-html", HelpText="Allows HTML tags in the markdown source to be passed through to the output markdown.")]
         public bool AllowUnsafeHtmlContentInMarkdown { get; set; }
 

ApiDocs.Console/Program.cs

@@ -230,7 +230,15 @@ private static Task<DocSet> GetDocSetAsync(DocSetOptions options)
 
             FancyConsole.VerboseWriteLine("Scanning documentation files...");
             ValidationError[] loadErrors;
-            if (!set.ScanDocumentation(out loadErrors))
+
+            string tagsToInclude = string.Empty;
+            if (options.PageParameterDict != null &&
+                options.PageParameterDict.ContainsKey("tags"))
+            {
+                tagsToInclude = options.PageParameterDict["tags"]?.ToString();
+            }
+
+            if (!set.ScanDocumentation(tagsToInclude, out loadErrors))
             {
                 FancyConsole.WriteLine("Errors detected while parsing documentation set:");
                 WriteMessages(loadErrors, false, "  ", false);

ApiDocs.Publishing/Html/DocumentPublisherHtml.cs

@@ -36,13 +36,15 @@ namespace ApiDocs.Publishing.Html
     using ApiDocs.Validation.Writers;
     using MarkdownDeep;
     using Newtonsoft.Json;
+    using Validation.Tags;
 
     public class DocumentPublisherHtml : DocumentPublisher
     {
         protected string TemplateHtml;
 
         public string HtmlOutputExtension { get; set; }
         public string TemplateHtmlFilename { get; set; }
+        protected Dictionary<string, object> PageParameters { get; set; }
 
         /// <summary>
         /// Allow HTML tags in the markdown source to pass through to the converted HTML. This is considered
@@ -56,6 +58,7 @@ public DocumentPublisherHtml(DocSet docs, IPublishOptions options)
             TemplateHtmlFilename =  options.TemplateFilename ?? "template.htm";
             HtmlOutputExtension = options.OutputExtension ?? ".htm";
             EnableHtmlTagPassThrough = options.AllowUnsafeHtmlContentInMarkdown;
+            PageParameters = options.PageParameterDict;
         }
 
         /// <summary>
@@ -185,6 +188,7 @@ protected static void SplitUrlPathAndBookmark(string input, out string url, out
         /// <returns></returns>
         protected virtual Markdown GetMarkdownConverter()
         {
+            //var converter = new Markdown
             var converter = new Markdown
             {
                 ExtraMode = true,
@@ -226,24 +230,13 @@ protected override async Task PublishFileToDestinationAsync(FileInfo sourceFile,
 
             var destinationPath = this.GetPublishedFilePath(sourceFile, destinationRoot, HtmlOutputExtension);
 
-            StringWriter writer = new StringWriter();
-            StreamReader reader = new StreamReader(sourceFile.OpenRead());
-
-            long lineNumber = 0;
-            string nextLine;
-            while ((nextLine = await reader.ReadLineAsync()) != null)
-            {
-                lineNumber++;
-                if (this.IsDoubleBlockQuote(nextLine))
-                {
-                    this.LogMessage(new ValidationMessage(string.Concat(sourceFile.Name, ":", lineNumber), "Removing DoubleBlockQuote"));
-                    continue;
-                }
-                await writer.WriteLineAsync(nextLine);
-            }
+            // Create a tag processor
+            TagProcessor tagProcessor = new TagProcessor(PageParameters?["tags"]?.ToString(),
+                page.Parent.SourceFolderPath, LogMessage);
 
             var converter = this.GetMarkdownConverter();
-            var html = converter.Transform(writer.ToString());
+            var html = converter.Transform(tagProcessor.Preprocess(sourceFile));
+            html = await tagProcessor.PostProcess(html, sourceFile, converter);
 
             var pageData = page.Annotation ?? new PageAnnotation();
             if (string.IsNullOrEmpty(pageData.Title))

ApiDocs.Publishing/Html/HtmlMustacheWriter.cs

@@ -39,15 +39,13 @@ public class HtmlMustacheWriter : DocumentPublisherHtml
     {
         private Generator generator;
         private FileTagDefinition fileTag;
-        private Dictionary<string, object> PageParameters { get; set; }
 
         public bool CollapseTocToActiveGroup { get; set; }
 
 
         public HtmlMustacheWriter(DocSet docs, IPublishOptions options) : base(docs, options)
         {
             this.CollapseTocToActiveGroup = false;
-            this.PageParameters = GeneratePageParameters(options);
         }
 
         protected override void LoadTemplate()
@@ -129,21 +127,6 @@ protected override async Task WriteAdditionalFilesAsync()
             }
         }
 
-        private static Dictionary<string, object> GeneratePageParameters(IPublishOptions options)
-        {
-            if (string.IsNullOrEmpty(options.AdditionalPageParameters))
-                return null;
-
-            var data = new Dictionary<string, object>();
-
-            var parameters = Validation.Http.HttpParser.ParseQueryString(options.AdditionalPageParameters);
-            foreach (var key in parameters.AllKeys)
-            {
-                data[key] = parameters[key];
-            }
-            return data;
-        }
-
         private class PageTemplateInput
         {
             public PageAnnotation Page { get; set; }

ApiDocs.Validation.UnitTests/DocFileForTesting.cs

@@ -37,7 +37,7 @@ public DocFileForTesting(string contentsOfFile, string fullPath, string displayN
             this.Parent = parent;
         }
 
-        protected override string GetContentsOfFile()
+        protected override string GetContentsOfFile(string tags)
         {
             return this.contentsOfFile;
         }

ApiDocs.Validation.UnitTests/ResourceStringValidationTests.cs

@@ -41,7 +41,7 @@ static DocFile GetDocFile()
             DocFile testFile = new DocFileForTesting(Resources.ExampleResources, "\resources.md", "\resources.md", docSet);
 
             ValidationError[] detectedErrors;
-            testFile.Scan(out detectedErrors);
+            testFile.Scan(string.Empty, out detectedErrors);
 
             Assert.IsFalse(detectedErrors.WereWarningsOrErrors(), "Detected warnings or errors when reading the example markdown file.");
 

ApiDocs.Validation.UnitTests/SchemaValidatorTests.cs

@@ -159,7 +159,7 @@ public void TruncatedExampleWithRequiredPropertiesTest()
             DocFile testFile = new DocFileForTesting(Resources.ExampleValidateResponse, "\test\test.md", "test.md", docSet);
 
             ValidationError[] detectedErrors;
-            testFile.Scan(out detectedErrors);
+            testFile.Scan(string.Empty, out detectedErrors);
 
             Assert.IsEmpty(detectedErrors.Where(x => x.IsError));
 
@@ -185,7 +185,7 @@ public void TruncatedExampleSelectStatementOnChildren()
             DocFile testFile = new DocFileForTesting(Resources.ExampleValidationSelectStatement, "\test\test.md", "test.md", docSet);
 
             ValidationError[] detectedErrors;
-            testFile.Scan(out detectedErrors);
+            testFile.Scan(string.Empty, out detectedErrors);
 
             Assert.IsEmpty(detectedErrors.Where(x => x.IsError));
 
@@ -209,7 +209,7 @@ public void TruncatedExampleSelectStatementOnChildrenExpectFailure()
             DocFile testFile = new DocFileForTesting(Resources.ExampleValidationSelectStatementFailure, "\test\test.md", "test.md", docSet);
 
             ValidationError[] detectedErrors;
-            testFile.Scan(out detectedErrors);
+            testFile.Scan(string.Empty, out detectedErrors);
 
             Assert.IsEmpty(detectedErrors.Where(x => x.IsError));
 

ApiDocs.Validation/ApiDocs.Validation.csproj

@@ -88,6 +88,7 @@
     <Compile Include="ScenarioExtensionMethods.cs" />
     <Compile Include="TableSpec\TableDefinition.cs" />
     <Compile Include="TableSpec\TableParserConfig.cs" />
+    <Compile Include="Tags\TagProcessor.cs" />
     <Compile Include="ValidationConfig.cs" />
     <Compile Include="Writers\MarkdownPublisher.cs.cs" />
     <Compile Include="Writers\DocumentPublisher.cs" />

ApiDocs.Validation/DocFile.cs

@@ -32,6 +32,7 @@ namespace ApiDocs.Validation
     using System.Linq;
     using ApiDocs.Validation.Error;
     using ApiDocs.Validation.TableSpec;
+    using Tags;
     using MarkdownDeep;
     using Newtonsoft.Json;
 
@@ -150,26 +151,26 @@ protected void TransformMarkdownIntoBlocksAndLinks(string inputMarkdown)
             this.MarkdownLinks = new List<ILinkInfo>(md.FoundLinks);
         }
 
-        protected virtual string GetContentsOfFile()
+        protected virtual string GetContentsOfFile(string tags)
         {
-            using (StreamReader reader = File.OpenText(this.FullPath))
-            {
-                return reader.ReadToEnd();
-            }
+            // Preprocess file content
+            FileInfo docFile = new FileInfo(this.FullPath);
+            TagProcessor tagProcessor = new TagProcessor(tags, Parent.SourceFolderPath);
+            return tagProcessor.Preprocess(docFile);
         }
 
 
         /// <summary>
         /// Read the contents of the file into blocks and generate any resource or method definitions from the contents
         /// </summary>
-        public bool Scan(out ValidationError[] errors)
+        public bool Scan(string tags, out ValidationError[] errors)
         {
             this.HasScanRun = true;
             List<ValidationError> detectedErrors = new List<ValidationError>();
 
             try
             {
-                this.TransformMarkdownIntoBlocksAndLinks(this.GetContentsOfFile());
+                this.TransformMarkdownIntoBlocksAndLinks(this.GetContentsOfFile(tags));
             }
             catch (IOException ioex)
             {
@@ -928,7 +929,13 @@ public bool ValidateNoBrokenLinks(bool includeWarnings, out ValidationError[] er
             {
                 if (null == link.Definition)
                 {
-                    foundErrors.Add(new ValidationError(ValidationErrorCode.MissingLinkSourceId, this.DisplayName, "Link specifies ID '{0}' which was not found in the document.", link.Text));
+                    // Don't treat TAGS or END markers like links
+                    if (!link.Text.ToUpper().Equals("END") && !link.Text.ToUpper().StartsWith("TAGS="))
+                    {
+                        foundErrors.Add(new ValidationError(ValidationErrorCode.MissingLinkSourceId, this.DisplayName, 
+                            "Link specifies ID '{0}' which was not found in the document.", link.Text));
+                    }
+
                     continue;
                 }
 

ApiDocs.Validation/DocSet.cs

@@ -217,14 +217,15 @@ public static string ResolvePathWithUserRoot(string path)
                 var userFolderPath = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
                 return Path.Combine(userFolderPath, path.Substring(2));
             }
-            return path;
+            // Return absolute path
+            return Path.GetFullPath(path);
         }
 
         /// <summary>
         /// Scan all files in the documentation set to load
         /// information about resources and methods defined in those files
         /// </summary>
-        public bool ScanDocumentation(out ValidationError[] errors)
+        public bool ScanDocumentation(string tags, out ValidationError[] errors)
         {
             var foundResources = new List<ResourceDefinition>();
             var foundMethods = new List<MethodDefinition>();
@@ -245,7 +246,7 @@ public bool ScanDocumentation(out ValidationError[] errors)
             foreach (var file in this.Files)
             {
                 ValidationError[] parseErrors;
-                if (!file.Scan(out parseErrors))
+                if (!file.Scan(tags, out parseErrors))
                 {
                     detectedErrors.AddRange(parseErrors);
                 }