Skip to content

Commit

Permalink
Add document convention (SimonCropp#275)
Browse files Browse the repository at this point in the history
  • Loading branch information
@SimonCropp
SimonCropp authored Aug 17, 2020
1 parent f7b4bc5 commit 484e847
Show file tree
Hide file tree
Showing 78 changed files with 873 additions and 357 deletions.
2 changes: 1 addition & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ run-git.cmd

*.jtconfig
NugetBuild
*.received.txt
*.received.*

.vs/
src/Tests/DirectoryMarkdownProcessor/Convention/one.md
Expand Down
9 changes: 5 additions & 4 deletions docs/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ var files = Directory.EnumerateFiles(@"C:\path", "*.cs", SearchOption.AllDirecto
var snippets = FileSnippetExtractor.Read(files);
```
<sup><a href='/src/Tests/Snippets/Usage.cs#L9-L15' title='File snippet `readingfilessimple` was extracted from'>snippet source</a> | <a href='#snippet-readingfilessimple' title='Navigate to start of snippet `readingfilessimple`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## Reading snippets from a directory structure
Expand All @@ -39,7 +39,7 @@ var snippetExtractor = new DirectorySnippetExtractor(
var snippets = snippetExtractor.ReadSnippets(@"C:\path");
```
<sup><a href='/src/Tests/Snippets/Usage.cs#L42-L51' title='File snippet `readingdirectorysimple` was extracted from'>snippet source</a> | <a href='#snippet-readingdirectorysimple' title='Navigate to start of snippet `readingdirectorysimple`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## Full Usage
Expand All @@ -59,6 +59,7 @@ var includes = includeFinder.ReadIncludes(directory);

// Merge with some markdown text
var markdownProcessor = new MarkdownProcessor(
convention: DocumentConvention.SourceTransform,
snippets: snippets.Lookup,
includes: includes,
appendSnippetGroup: SimpleSnippetMarkdownHandling.AppendGroup,
Expand All @@ -78,8 +79,8 @@ var missingSnippets = result.MissingSnippets;
// snippets that the markdown file used
var usedSnippets = result.UsedSnippets;
```
<sup><a href='/src/Tests/Snippets/Usage.cs#L56-L89' title='File snippet `markdownprocessingsimple` was extracted from'>snippet source</a> | <a href='#snippet-markdownprocessingsimple' title='Navigate to start of snippet `markdownprocessingsimple`'>anchor</a></sup>
<!-- endsnippet -->
<sup><a href='/src/Tests/Snippets/Usage.cs#L56-L90' title='File snippet `markdownprocessingsimple` was extracted from'>snippet source</a> | <a href='#snippet-markdownprocessingsimple' title='Navigate to start of snippet `markdownprocessingsimple`'>anchor</a></sup>
<!-- endSnippet -->


## Ignored paths
Expand Down
2 changes: 1 addition & 1 deletion docs/config-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Add a file named `mdsnippets.json` at the target directory with the following co
}
```
<sup><a href='/src/ConfigReader.Tests/sampleConfig.json#L1-L15' title='File snippet `sampleConfig.json` was extracted from'>snippet source</a> | <a href='#snippet-sampleConfig.json' title='Navigate to start of snippet `sampleConfig.json`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## More Info
Expand Down
2 changes: 1 addition & 1 deletion docs/github-action.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ jobs:
shell: bash
```
<sup><a href='/docs/on-push-do-docs.yml#L1-L22' title='File snippet `on-push-do-docs.yml` was extracted from'>snippet source</a> | <a href='#snippet-on-push-do-docs.yml' title='Navigate to start of snippet `on-push-do-docs.yml`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->

This action performs the following tasks:

Expand Down
2 changes: 1 addition & 1 deletion docs/header.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Source File: {relativePath}
To change this file edit the source file and then run MarkdownSnippets.
```
<sup><a href='/src/Tests/HeaderWriterTests.DefaultHeader.verified.txt#L1-L4' title='File snippet `HeaderWriterTests.DefaultHeader.verified.txt` was extracted from'>snippet source</a> | <a href='#snippet-HeaderWriterTests.DefaultHeader.verified.txt' title='Navigate to start of snippet `HeaderWriterTests.DefaultHeader.verified.txt`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## Disable Header
Expand Down
2 changes: 1 addition & 1 deletion docs/max-width.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ var processor = new DirectoryMarkdownProcessor(
processor.Run();
```
<sup><a href='/src/Tests/Snippets/Usage.cs#L30-L37' title='File snippet `directorymarkdownprocessorrunmaxwidth` was extracted from'>snippet source</a> | <a href='#snippet-directorymarkdownprocessorrunmaxwidth' title='Navigate to start of snippet `directorymarkdownprocessorrunmaxwidth`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## References
Expand Down
2 changes: 1 addition & 1 deletion docs/mdsource/toc/tocAfter.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

* [Heading 1](#heading-1)
* [Heading 2](#heading-2)
<!-- endtoc -->
<!-- endToc -->

## Heading 1

Expand Down
2 changes: 1 addition & 1 deletion docs/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ To change this file edit the source file and then run MarkdownSnippets.
* [Header](/docs/header.md)
* Writing Documentation
* [Indentation](/docs/indentation.md)
* [Table of contents](/docs/toc.md) <!-- end include: doc-index. path: /docs/mdsource/doc-index.include.md -->
* [Table of contents](/docs/toc.md) <!-- endInclude -->
6 changes: 3 additions & 3 deletions docs/toc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Text1
Text2
```
<sup><a href='/docs/mdsource/toc/tocBefore.txt#L1-L11' title='File snippet `tocBefore.txt` was extracted from'>snippet source</a> | <a href='#snippet-tocBefore.txt' title='Navigate to start of snippet `tocBefore.txt`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->

The result will be rendered:

Expand All @@ -41,7 +41,7 @@ The result will be rendered:
* [Heading 1](#heading-1)
* [Heading 2](#heading-2)
<!-- endtoc -->
<!-- endToc -->
## Heading 1
Expand All @@ -52,7 +52,7 @@ Text1
Text2
```
<sup><a href='/docs/mdsource/toc/tocAfter.txt#L1-L16' title='File snippet `tocAfter.txt` was extracted from'>snippet source</a> | <a href='#snippet-tocAfter.txt' title='Navigate to start of snippet `tocAfter.txt`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


## Heading Level
Expand Down
10 changes: 5 additions & 5 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Support is available via a [Tidelift Subscription](https://tidelift.com/subscrip
* [Defining Snippets](#defining-snippets)
* [Using Snippets](#using-snippets)
* [More Documentation](#more-documentation)
* [Security contact information](#security-contact-information)<!-- endtoc -->
* [Security contact information](#security-contact-information)<!-- endToc -->


## Value Proposition
Expand Down Expand Up @@ -149,7 +149,7 @@ The resulting markdown will be:
My Snippet Code
```
<sup><a href='/relativeUrlToFile#L1-L11' title='File snippet `MySnippetName` was extracted from'>snippet source</a> | <a href='#snippet-MySnippetName' title='Navigate to start of snippet `MySnippetName`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->

Notes:

Expand All @@ -176,7 +176,7 @@ namespace MarkdownSnippets
}
```
<sup><a href='/src/MarkdownSnippets/Processing/LinkFormat.cs#L1-L10' title='File snippet `LinkFormat.cs` was extracted from'>snippet source</a> | <a href='#snippet-LinkFormat.cs' title='Navigate to start of snippet `LinkFormat.cs`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->

<!-- snippet: BuildLink -->
<a id='snippet-buildlink'></a>
Expand All @@ -202,7 +202,7 @@ if (linkFormat == LinkFormat.GitLab)
}
```
<sup><a href='/src/MarkdownSnippets/Processing/SnippetMarkdownHandling.cs#L103-L123' title='File snippet `buildlink` was extracted from'>snippet source</a> | <a href='#snippet-buildlink' title='Navigate to start of snippet `buildlink`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->


### UrlPrefix
Expand All @@ -226,7 +226,7 @@ UrlPrefix allows a string to be defined that will prefix all snippet links. This
* [Header](/docs/header.md)
* Writing Documentation
* [Indentation](/docs/indentation.md)
* [Table of contents](/docs/toc.md) <!-- end include: doc-index. path: /docs/mdsource/doc-index.include.md -->
* [Table of contents](/docs/toc.md) <!-- endInclude -->


## Security contact information
Expand Down
2 changes: 1 addition & 1 deletion readme.source.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ The resulting markdown will be:
My Snippet Code
```
<sup><a href='/relativeUrlToFile#L1-L11' title='File snippet `MySnippetName` was extracted from'>snippet source</a> | <a href='#snippet-MySnippetName' title='Navigate to start of snippet `MySnippetName`'>anchor</a></sup>
<!-- endsnippet -->
<!-- endSnippet -->

Notes:

Expand Down
8 changes: 5 additions & 3 deletions src/ConfigReader/ConfigDefaults.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ public static ConfigResult Convert(ConfigInput? fileConfig, ConfigInput otherCon
{
ValidateContent = otherConfig.ValidateContent.GetValueOrDefault(),
ReadOnly = otherConfig.ReadOnly.GetValueOrDefault(),
WriteHeader = otherConfig.WriteHeader.GetValueOrDefault(true),
WriteHeader = otherConfig.WriteHeader,
LinkFormat = otherConfig.LinkFormat.GetValueOrDefault(LinkFormat.GitHub),
Convention = otherConfig.Convention.GetValueOrDefault(DocumentConvention.SourceTransform),
Exclude = otherConfig.Exclude,
Header = otherConfig.Header,
UrlPrefix = otherConfig.UrlPrefix,
Expand All @@ -29,9 +30,10 @@ public static ConfigResult Convert(ConfigInput? fileConfig, ConfigInput otherCon
return new ConfigResult
{
ValidateContent = GetValueOrDefault("ValidateContent", otherConfig.ValidateContent, fileConfig.ValidateContent, false),
ReadOnly = GetValueOrDefault("ReadOnly", otherConfig.ReadOnly, fileConfig.ReadOnly, false),
WriteHeader = GetValueOrDefault("WriteHeader", otherConfig.WriteHeader, fileConfig.WriteHeader, true),
ReadOnly = GetValueOrNull("ReadOnly", otherConfig.ReadOnly, fileConfig.ReadOnly),
WriteHeader = GetValueOrNull("WriteHeader", otherConfig.WriteHeader, fileConfig.WriteHeader),
LinkFormat = GetValueOrDefault("LinkFormat", otherConfig.LinkFormat, fileConfig.LinkFormat, LinkFormat.GitHub),
Convention = GetValueOrDefault("Mode", otherConfig.Convention, fileConfig.Convention, DocumentConvention.SourceTransform),
TocLevel = GetValueOrDefault("TocLevel", otherConfig.TocLevel, fileConfig.TocLevel, 2),
MaxWidth = GetValueOrDefault("MaxWidth", otherConfig.MaxWidth, fileConfig.MaxWidth, int.MaxValue),
Header = GetValueOrDefault("Header", otherConfig.Header, fileConfig.Header),
Expand Down
1 change: 1 addition & 0 deletions src/ConfigReader/ConfigInput.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ public class ConfigInput
public bool? ReadOnly { get; set; }
public bool? ValidateContent { get; set; }
public LinkFormat? LinkFormat { get; set; }
public DocumentConvention? Convention { get; set; }
public int? TocLevel { get; set; }
public int? MaxWidth { get; set; }
public List<string> UrlsAsSnippets { get; set; } = new List<string>();
Expand Down
44 changes: 30 additions & 14 deletions src/ConfigReader/ConfigReader.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,25 +47,41 @@ public static ConfigInput Parse(string contents)
Position = 0
};
var serializer = new DataContractJsonSerializer(typeof(ConfigSerialization));
var configSerialization = (ConfigSerialization) serializer.ReadObject(stream);
var config = (ConfigSerialization) serializer.ReadObject(stream);
return new ConfigInput
{
WriteHeader = configSerialization.WriteHeader,
ReadOnly = configSerialization.ReadOnly,
ValidateContent = configSerialization.ValidateContent,
UrlsAsSnippets = configSerialization.UrlsAsSnippets,
Exclude = configSerialization.Exclude,
Header = configSerialization.Header,
UrlPrefix = configSerialization.UrlPrefix,
TocExcludes = configSerialization.TocExcludes,
DocumentExtensions = configSerialization.DocumentExtensions,
TocLevel = configSerialization.TocLevel,
MaxWidth = configSerialization.MaxWidth,
LinkFormat = GetLinkFormat(configSerialization.LinkFormat),
TreatMissingAsWarning = configSerialization.TreatMissingAsWarning,
WriteHeader = config.WriteHeader,
ReadOnly = config.ReadOnly,
ValidateContent = config.ValidateContent,
UrlsAsSnippets = config.UrlsAsSnippets,
Exclude = config.Exclude,
Header = config.Header,
UrlPrefix = config.UrlPrefix,
TocExcludes = config.TocExcludes,
DocumentExtensions = config.DocumentExtensions,
TocLevel = config.TocLevel,
MaxWidth = config.MaxWidth,
LinkFormat = GetLinkFormat(config.LinkFormat),
Convention = GetConvention(config.Convention),
TreatMissingAsWarning = config.TreatMissingAsWarning,
};
}

static DocumentConvention? GetConvention(string? value)
{
if (value == null)
{
return null;
}

if (Enum.TryParse<DocumentConvention>(value, out var convention))
{
return convention;
}

throw new ConfigurationException($"Failed to parse DocumentConvention: {convention}");
}

static LinkFormat? GetLinkFormat(string? value)
{
if (value == null)
Expand Down
5 changes: 3 additions & 2 deletions src/ConfigReader/ConfigResult.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,15 @@

public class ConfigResult
{
public bool ReadOnly;
public bool? ReadOnly;
public bool ValidateContent;
public LinkFormat LinkFormat;
public DocumentConvention Convention;
public int TocLevel;
public int MaxWidth;
public List<string> UrlsAsSnippets = new List<string>();
public List<string> Exclude = new List<string>();
public bool WriteHeader;
public bool? WriteHeader;
public string? Header;
public string? UrlPrefix;
public List<string> TocExcludes = new List<string>();
Expand Down
1 change: 1 addition & 0 deletions src/ConfigReader/ConfigSerialization.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ public class ConfigSerialization
public bool? ReadOnly { get; set; }
public bool? ValidateContent { get; set; }
public string? LinkFormat { get; set; }
public string? Convention { get; set; }
public bool? WriteHeader { get; set; }
public string? Header { get; set; }
public string? UrlPrefix { get; set; }
Expand Down
2 changes: 2 additions & 0 deletions src/ConfigReader/LogBuilder.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ public static string BuildConfigLogMessage(string root, ConfigResult config, str
Header: {header}
UrlPrefix: {config.UrlPrefix}
LinkFormat: {config.LinkFormat}
Convention: {config.Convention}
TocLevel: {config.TocLevel}
MaxWidth: {config.MaxWidth}
ValidateContent: {config.ValidateContent}
Expand All @@ -26,6 +27,7 @@ public static string BuildConfigLogMessage(string root, ConfigResult config, str
builder.AppendLine($@" Exclude:
{string.Join("\r\n ", config.Exclude)}");
}

if (config.TocExcludes.Any())
{
builder.AppendLine($@" TocExcludes:
Expand Down
3 changes: 3 additions & 0 deletions src/MarkdownSnippets.MsBuild/DocoTask.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ public class DocoTask :
public int? TocLevel { get; set; }
public int? MaxWidth { get; set; }
public LinkFormat? LinkFormat { get; set; }
public DocumentConvention? Convention { get; set; }
public List<string> Exclude { get; set; } = new List<string>();
public List<string> TocExcludes { get; set; } = new List<string>();
public List<string> UrlsAsSnippets { get; set; } = new List<string>();
Expand All @@ -41,6 +42,7 @@ public override bool Execute()
Header = Header,
UrlPrefix = UrlPrefix,
LinkFormat = LinkFormat,
Convention = Convention,
Exclude = Exclude,
TocExcludes = TocExcludes,
TocLevel = TocLevel,
Expand All @@ -62,6 +64,7 @@ public override bool Execute()
header: configResult.Header,
urlPrefix: configResult.UrlPrefix,
linkFormat: configResult.LinkFormat,
convention: configResult.Convention,
tocLevel: configResult.TocLevel,
tocExcludes: configResult.TocExcludes,
documentExtensions: configResult.DocumentExtensions,
Expand Down
5 changes: 5 additions & 0 deletions src/MarkdownSnippets.Tool/Options.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,11 @@ public class Options
HelpText = "Controls the format of the link under each snippet. Optional. Supported values: GitHub, Tfs. Defaults to GitHub.")]
public LinkFormat? LinkFormat { get; set; }

[Option('c', "convention",
Required = false,
HelpText = "Controls the target document convention. Optional. Supported values: SourceTransform, InPlaceOverwrite. Defaults to SourceTransform.")]
public DocumentConvention? Convention { get; set; }

[Option("toc-level",
Required = false,
HelpText = "Controls how many header levels to write in the table of contents. Optional. Defaults to 2. Must be positive.")]
Expand Down
1 change: 1 addition & 0 deletions src/MarkdownSnippets.Tool/Program.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ static async Task Inner(string targetDirectory, ConfigInput configInput)
header: configResult.Header,
urlPrefix: configResult.UrlPrefix,
linkFormat: configResult.LinkFormat,
convention: configResult.Convention,
tocExcludes: configResult.TocExcludes,
documentExtensions: configResult.DocumentExtensions,
tocLevel: configResult.TocLevel,
Expand Down
Loading

0 comments on commit 484e847

Please sign in to comment.