LiterateCS is a console tool and it is controlled primarily through command line options. Command Line Parser Library is used to parse the options. It simplifies the process and allows us to define new parameters just by adding properties to the Option class.
namespace LiterateCS
{
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using ExtensionCord;
using CommandLine;
using CommandLine.Text;
using YamlDotNet.Core;
using YamlDotNet.Core.Events;
using YamlDotNet.Serialization;
using LiterateCS.Theme;
The output format is either HTML or Markdown. The following enumeration is used to define the possible options.
public enum OutputFormat { md, html }
The Option class defines the available command line options as properties. These properties are decorated by attributes that specify the short and long format of the option, whether the option is mandatory or not, and the associated help text. Also, the name of the option in a YAML file is specified. The type of an option (boolean, string, enumeration, etc.) is inferred from the type of the associated property.
public class Options
{
There are two special input files which are processed separately. They
are defined in YAML format and they have fixed names.
The first one is the defaults.yml file which contains the default settings
used by LiterateCS. This file will be processed before any of the other files,
so all the global (project-level) properties should be defined in it.
The first part of the file contains front matter defaults. See the chapter on
Front Matter to learn about available properties. The
second part of the file contains the default command line arguments. The
processing order is that defaults.yml file will be read first and all the
command line arguments found there are used as default values. However, if
the same option is specified in the command line, it overrides the setting
found in the defaults file. If an option is not present in the defaults file
or in the command line, the application-level default value is used.
public const string DefaultsFile = "defaults.yml";
The other special file is the table of contents or TOC for short. Its file
name is TOC.yml and its structure is described in
its own section. You can add entries to TOC manually,
or use the -u option to automatically update it when files are missing from it.
public const string TocFile = "TOC.yml";
The arguments given without option specifiers - or -- are assumed to be filters
that specify what files are processed by the tool. You can give multiple filters or file
names to be searched for. The filters may contain literal text and three kinds of
wildcards that conform to the glob convention:
? matches a single character.* matches zero or more occurrences of any character except \. So, this wild card
basically matches a part of a file or a directory name.** matches zero or more occurrences of any character including the backslash. This
wildcard can be used to select files that reside in subdirectories.The file names that are matched against the filters are given relative either to the input folder or to the solution folder.
private IEnumerable<string> _filters;
[Value (0, MetaName = "<filters>",
HelpText = "Filters for input files; both source and markdown.")]
[YamlMember (Alias = "filters")]
public IEnumerable<string> Filters
{
get => _filters;
set
{
This bit of logic prevents command line parser from overriding
filters read from defaults.yml with an empty list.
if ((value != null && value.Any ()) ||
_filters == null || _filters.None ())
_filters = value;
}
}
Instead of using the input folder get the files to be processed from a MSBuild solution.
[Option ('s', "solution", Required = false,
HelpText = "Read the the C# and markdown files from a msbuild solution (*.sln). " +
"If this option is specified, the '--input' option is ignored.")]
[YamlMember (Alias="solution")]
public string Solution { get; set; }
Input folder specifies the root of your source files. Typically you want to process
all the C# and markdown files in the source folder, so you define it with the -i
option and give *.cs and *.md as filters. If this option is omitted, the current
directory is assumed to be the input directory.
[Option ('i', "input", Required = false,
HelpText = "The root folder for the files to be processed. Files under this " +
"directory are checked against the filters. If input folder is not specified, the " +
"current directory is used.")]
[YamlMember (Alias = "input")]
public string InputFolder { get; set; }
The output folder specifies where the tool stores the generated files. The output folder will contain the markdown and HTML files, as well as all the auxiliary files (CSS, Javascript, etc.) needed by the documents. If a relative path is specified, then it is relative to the input folder or solution folder. If nothing is specified, the default output folder is set to "docs/" under the input folder.
[Option ('o', "output", Required = false,
HelpText = "Output folder where the documentation will be generated to. "+
"The default output folder is <input|solutionfolder>/docs.")]
[YamlMember (Alias = "output")]
public string OutputFolder { get; set; } = "docs";
LiterateCS needs to recognize which of the input files are source (C#) files, and
which ones are markdown files. Typically source files have the .cs extension. If
you are using a different file extension, you can specify it with the -e option.
[Option ('e', "csext",
HelpText = "File extension for the C# source files. Used to identify source files " +
"in the input folder. The default is '.cs'")]
[YamlMember (Alias = "csext")]
public string SourceExt { get; set; } = ".cs";
Similarly to C# files, markdown files are recognized by the file extension. If not
specified, .md is assumed to be the extension.
[Option ('d', "mdext",
HelpText = "File extension for the markdown files. Used to identify markdown files " +
"in the input folder. The default is '.md'")]
[YamlMember (Alias = "mdext")]
public string MarkdownExt { get; set; } = ".md";
Output format is specified by the -f option. Only valid values are md for markdown
and html for HTML documents.
[Option ('f', "format",
HelpText = "Format of the outputted documentation; either 'md' or 'html'. " +
"Default is 'md'")]
[YamlMember (Alias = "format")]
public OutputFormat Format { get; set; }
The --trim argument indicates whether comments extracted from the source files will be
left-trimmed. Visual Studio likes to indent the comment blocks automatically to the same
level as the code. When these comment lines are extracted they will contain the leading
spaces or tabs that appear in the source file. If not trimmed, these lines will be
interpreted as code blocks in the markdown, which is not what we usually want. So, if you
have indented comments that you want to be considered as normal text in markdown, include
this option in your arguments.
[Option ('t', "trim",
HelpText = "Left-trim the comments before processing them to avoid interpreting " +
"them as code blocks.")]
[YamlMember (Alias = "trim")]
public bool Trim { get; set; }
If you want LiterateCS to automatically add the files it processes to the table of
contents file (TOC.yml), enable this option. This makes maintaining the TOC file
easier and reminds you to update it after new files have been added.
[Option ('u', "updatetoc",
HelpText = "Adds processed files that are not already in the TOC file to it.")]
[YamlMember (Alias = "updatetoc")]
public bool UpdateToc { get; set; }
Themes are .NET assemblies which transform parsed code and text into HTML documents
using page templates. In addition, themes manage the auxiliary CSS, JS, and font files
that need to be copied to the target folder. The default theme is provided by LiterateCS,
but if you want, you can clone it and customize it to your liking. The --theme option
should be specified, if you want to use a custom theme.
[Option ('m', "theme",
HelpText = "The theme DLL which generates HTML documents according to page " +
"templates. If not specified, the default theme is used.")]
[YamlMember (Alias = "theme")]
public string Theme { get; set; } = "DefaultTheme.dll";
When a solution file is used as an input, LiterateCS first builds the solution to
determine all its dependencies. If you want to get a log file of the build for
troubleshooting, use the --buildlog option.
[Option ('b', "buildlog", Required = false,
HelpText = "Path to the build log file.")]
[YamlMember (Alias = "buildlog")]
public string BuildLog { get; set; }
If you want the tool to output information as it processes files, you can use the verbose option.
[Option ('v', "verbose",
HelpText = "Outputs information about processed files to the standard output.")]
[YamlMember (Alias = "verbose")]
public bool Verbose { get; set; }
In order to make reading and parsing of the file and directory paths simpler, we will define few helper properties that present them as SplitPath structures. The idea behind this data type is explained on its own documentation page, but in a nutshell its main purpose is to separate the two parts of a file path: the absolute base path and the relative file path. Doing this makes the code that needs these paths more succinct and readable. It also makes converting paths to hyperlinks easier.
The files produced by LiterateCS are stored in a similar directory hierarchy as the
input files. The base directory for the input files is defined by the -i option, or
if a solution file is provided (with the -s option), the base input directory will
be the one where the solution file resides. If neither is given, the current directory
is used as the base input path.
public SplitPath InputPath =>
Solution != null ? SplitPath.Base (Path.GetDirectoryName (Solution)) :
InputFolder != null ? SplitPath.Base (InputFolder) :
SplitPath.Base (Directory.GetCurrentDirectory ());
The output base path is given with the mandatory -o option. The OutputPath property
just wraps it inside the SplitPath structure.
public SplitPath OutputPath =>
SplitPath.Base (OutputFolder);
Lastly, the theme path is constructed. The base path of the theme is the directory where the theme DLL resides. If the theme path given as an option is not an absolute one, it is assumed that the path points to a folder under the application directory (where the executables reside).
public SplitPath ThemePath
{
get
{
var fullPath = Path.IsPathRooted (Theme) ? Theme :
Path.Combine (
Path.GetDirectoryName (Assembly.GetEntryAssembly ().Location),
Theme);
return new SplitPath (Path.GetDirectoryName (fullPath),
Path.GetFileName (fullPath));
}
}
defaults.ymlTypically you run the literatecs command with the same options again and
again. For this reason, it is usually easier to specify the options in the
defaults.yml file. You can still override the options in the command line
if desired, but the initial values will be fetched from the defaults file.
If it does not appear there either, the application default is used.
public static Options LoadFromDefaultsFile ()
{
if (!File.Exists (DefaultsFile))
return new Options ();
Console.WriteLine ("Reading default command line options from '{0}'",
DefaultsFile);
try
{
We use the YamlDotNet serialization to read the file.
using (var input = File.OpenText (DefaultsFile))
{
var deserializer = new DeserializerBuilder ()
.Build ();
var parser = new YamlDotNet.Core.Parser (input);
We skip the first document, which contains the front matter defaults.
parser.Consume<StreamStart> ();
deserializer.Deserialize<Dictionary<string, string>> (parser);
Then we can deserialize the default command line options.
var result = deserializer
.Deserialize<Options> (parser);
If no settings could be found, we return an Option object initialized with application-level defaults.
return result ?? new Options ();
}
}
catch (YamlException e)
{
throw new LiterateException (
"Invalid syntax in the 'defaults.yml' file. Make sure that the YAML data " +
"is defined according to the specification.",
DefaultsFile, "http://yaml.org/", e);
}
}
After both defaults file and command line argument are parsed, it is good to check that all effective options are correct. For that we will provide a method that outputs all the options as a command line. We utilize the new feature in the Command Line Parser library, which "unparses" the option object back to command line arguments.
public void OutputEffectiveOptions ()
{
Console.WriteLine ("Command line options used:");
Console.WriteLine (CommandLine.Parser.Default.FormatCommandLine (this));
}
Below are some example command lines for the most common usage scenarios.
[Usage (ApplicationAlias = "literatecs")]
public static IEnumerable<Example> Examples =>
new Example[]
{
The following command line processes all C# and markdown files in a
solution (including all projects and subfolders), and generates markdown
output to a directory called "docs". It also includes the -t switch to
strip the indentation from the comments. This setting is usually on.
literatecs **.cs **.md -s <solution>.sln -o docs -f md -t
Below we construct this example using an instance of Options class.
Command Line Parser shows this example in the help screen which is
outputted whenever there are errors in the command line, or when the
--help option is specified.
new Example ("Generate markdown documentation for a solution",
new UnParserSettings
{
PreferShortName = true,
GroupSwitches = true
},
new Options
{
Filters = new string[] { "**.cs", "**.md" },
Solution = "<solution>.sln",
OutputFolder = "docs",
Format = OutputFormat.md,
Trim = true
}),
The example below scans the subfolder "src" for C# files, and the root folder for markdown files. It produces HTML and outputs information to console for each processed file (verbose option).
Note: Since we are just reading individual files C# files inside a directory and do not provide a solution file, LiterateCS cannot use Roslyn to compile the code and produce semantic information. So, the syntax highlighting is limited to basic tokens, and the links and type information is not available in the produced HTML files.
literatecs src\*.cs *.md -i <root> -o docs -f html -tv
new Example ("Create HTML documentation from files in a directory",
new UnParserSettings
{
PreferShortName = true,
GroupSwitches = true
},
new Options
{
Filters = new string[] { "src\\*.cs", "*.md" },
InputFolder = "<root>",
OutputFolder = "docs",
Format = OutputFormat.html,
Trim = true,
Verbose = true
}),
The last example uses all the available functionality. It produces documentation for the LiterateCS tool itself. It specifies the solution file, and processes C# files under "src" subdirectory, along with the markdown files under the solution directory.
Table of contents file is updated while the files are processed. This is specified
with the -u switch.
literatecs src\*.cs *.md -s <solution>.sln -o docs -f html -tuv
new Example ("Create HTML documentation for a solution",
new UnParserSettings
{
PreferShortName = true,
GroupSwitches = true
},
new Options
{
Filters = new string[] { "src\\*.cs", "*.md" },
Solution = "<solution>.sln",
OutputFolder = "docs",
Format = OutputFormat.html,
Trim = true,
UpdateToc = true,
Verbose = true
}),
Tip: If you think the command line above is a bit dense, you can also use the long format for the options to make them more understandable. The options are case-insensitive, so you can write them in any way you like.
literatecs src\*.cs *.md --solution <solution>.sln --output docs --format html --trim --UpdateTOC --verbose
new Example ("Same example with long option names",
new Options
{
Filters = new string[] { "src\\*.cs", "*.md" },
Solution = "<solution>.sln",
OutputFolder = "docs",
Format = OutputFormat.html,
Trim = true,
UpdateToc = true,
Verbose = true
})
};
}
}