We keep an internal base code platform at Nansen, which several of our sites are based. We like to think of this as our bread and butter. Meaning, those parts of every project you copy+paste to the next. Sadly, we have been quite bad at documenting it, or we have been documenting it, but the problem is often that the code examples tend to get out-of-date as code naturally evolve with time.To alleviate this I wanted to create a way to keep the documentation and examples to support it up-to-date, but also contain readable text. One could argue that an SDK is a way, but SDK's usually contain way too much fluff in the way of tables upon tables of method, property and event definitions. And they are also plagued by the out-of-date example code problem above, as examples are written in the <example>-section of the summary documentation. It is easy to get lazy and forget about an example if a method or class is updated.Anyways, my colleague Andreas 'Honungsprinsen' Oldeskog used a clever way to document our front-end framework by pulling markdown from github, and generating documentation pages from those files. I wanted to find a similar way, but with c# source code instead. This gave me three problems to solve:Having code examples that actually compile, and are relevant to the code I want to document.The ability to easily attach human readable documentation and informational text to said code.Some way of combining 1 and 2 in order to present it to the developers (hopefully) reading the documentation.Now, for problem 1, part of the solution was so simple Andreas had to point it out to me: Use tests! I could just write unit tests, they run the actual code, and you can use assertions to verify the examples actually do what you show to the reader of the documentation.The second part of the solution to problem 1 was finding a way to actually run the tests and present them to the reader. This was solved by using NUnit, and its test runner functionality somewhat hidden away in Nunit.core.dll, an assembly that is unfortunately not distributed along with nunit.framework.dll in the NUnit nuget package. I found it tucked away in a package named NUnit.Runners, and I had to manually reference the assemblies nunit.code.dll and nunit.core.interfaces.dll from my web project designated to run and present the results of my example tests.When all that is achieved, it is pretty simple to actually run tests:public class TestResultsEventListener : EventListener{ public TestResultsEventListener() { ListResults = new List<testresult>(); } public List<testresult> ListResults { get; } public void TestFinished(TestResult result) { ListResults.Add(result); } // noop all other methods}public List<testresult> RunSomeTests(IEnumerable<string> testNames){ var testPackage = new TestPackage("ExampleCode"); // this can be named anything testPackage.Assemblies.Add(Assembly.Load("my.assembly.with.tests").Location); var eventListener = new TestResultsEventListener(); var runner = new SimpleTestRunner(); if (runner.Load(_testPackage)) { var filter = TestFilter.Empty; if (testNames != null && testNames.Any()) { filter = new SimpleNameFilter(testNames.ToArray()); } runner.Run(eventListener, filter, true, LoggingThreshold.All); } return eventListener.ListResults;}The result is a neat list of all our tests and their results, this solved problem 1, neat!A bonus of this approach is also, since we use Episerver in our project platform, and the documentation/demo site is a basic implementation of said platform, all the service loading for epsierver is already done and the site is running so I can use real data for any code interacting with the site without having to mock my heart out (seriously, unit testing episerver code is 98% service mocking).For problem 2, I decided to just use markdown syntax in the summary documentation of each test. If a more generic description or informative text was needed, I used the summary documentation of the test class. I also made sure to comment as much as possible of the test method code.Now, problem 3 was trickier, I needed to somehow parse both the code and summary documentation for my test cases, and present the result. Cue Roslyn! Using the new Roslyn code parser Microsoft came up with, I could easily read a source file, and extract whatever I wanted.Combining all three solutions above gave me a helper that:Found all tests for a specific class,Ran the tests, and recorded the results,Parsed the source code for said tests and formatted the resultThe code for my helper:public class ExampleCodeHelper{ private readonly DirectoryInfo _baseDirectory; private readonly TestPackage _testPackage; public ExampleCodeHelper(string baseDirectory, IEnumerable<string> assemblyNames) { _baseDirectory = new DirectoryInfo(baseDirectory); _testPackage = new TestPackage("ExampleCode"); foreach (var assemblyName in assemblyNames) { _testPackage.Assemblies.Add(Assembly.Load(assemblyName).Location); } CoreExtensions.Host.InitializeService(); } public static ExampleCodeHelper Default { get { var root = HttpContext.Current.Server.MapPath("~") + ConfigurationManager.AppSettings["examplecode.sourcefile.rootpath"]; var assemblies = ConfigurationManager.AppSettings["examplecode.test.assemblies"].Split(';'); return new ExampleCodeHelper(root, assemblies); } } private IEnumerable<string> CodeFiles => Directory.GetFiles(_baseDirectory.FullName, "*.cs", SearchOption.AllDirectories); private IEnumerable<TestResult> RunTests(IEnumerable<string> testNames) { var eventListener = new TestResultsEventListener(); var runner = new SimpleTestRunner(); if (runner.Load(_testPackage)) { runner.Run(eventListener, new SimpleNameFilter(testNames.ToArray()), true, LoggingThreshold.All); } return eventListener.ListResults; } public ClassDeclarationSyntax GetTestClass(string classFullName) { var definitions = GetAllTestClassDefinitions(); var classSymbol = definitions.Keys.FirstOrDefault(k => k.ToString() == classFullName); return classSymbol != null ? definitions[classSymbol] : null; } /// <summary> /// Retrieves a <see cref="ExampleCodeContent"/> containing a number of <see cref="TestResultItem"/> objects with test results /// </summary> /// <param name="classFullName">Full name (including namespace) for the test class</param> public ExampleCodeContent GetTestResults(string classFullName) { var definitions = GetAllTestClassDefinitions(); var classSymbol = definitions.Keys.FirstOrDefault(k => k.ToString() == classFullName); if (classSymbol == null) { return null; } var classDeclaration = definitions[classSymbol]; var content = new ExampleCodeContent { Text = GetSyntaxNodeDocumentation(classSymbol), ContainerClass = classDeclaration }; var testCases = classDeclaration.DescendantNodes() .OfType<MethodDeclarationSyntax>() .Where(m => HasNamedAttribute(m.AttributeLists, nameof(TestAttribute))) .ToList(); var tests = RunTests(testCases.Select(t => $"{classSymbol.ToString()}.{t.Identifier.ValueText}")) .ToDictionary(key => testCases.Single(m => m.Identifier.ValueText == key.Test.MethodName), value => value); content.TestResults = tests.Keys.Select(method => new TestResultItem { Method = method, TestResult = tests[method], Text = GetSyntaxNodeDocumentation(GetDeclaredSymbol(method)) }).ToList(); return content; } /// <summary> /// Returns all test class definitions found in the defined source folder. /// </summary> /// <remarks> /// Only classes decorated with the <see cref="TestFixtureAttribute"/> attribute is returned. /// </remarks> public IDictionary<ISymbol, ClassDeclarationSyntax> GetAllTestClassDefinitions() { var classes = new List<ClassDeclarationSyntax>(); foreach (var file in CodeFiles) { try { var testClasses = CSharpSyntaxTree.ParseText(File.ReadAllText(file)) .GetRoot() .DescendantNodes() .OfType<ClassDeclarationSyntax>() .Where(c => HasNamedAttribute(c.AttributeLists, nameof(TestFixtureAttribute))); classes.AddRange(testClasses); } catch (Exception) { // just ignore failing source files } } return classes.ToDictionary(GetDeclaredSymbol, value => value); } #region helper methods private static bool HasNamedAttribute(SyntaxList<AttributeListSyntax> attributes, string attributeName) { var simpleAttributeName = attributeName.EndsWith("Attribute") ? attributeName.Substring(0, attributeName.LastIndexOf("Attribute", StringComparison.Ordinal)) : attributeName; return attributes.SelectMany(a => a.Attributes).Any(a => a.Name.ToString().EndsWith(simpleAttributeName)); } /// <summary> /// Retrives the <<paramref name="documentationSection"/>> documentation element "innertext" from the provided <see cref="ISymbol"/> /// </summary> private static string GetSyntaxNodeDocumentation(ISymbol symbol, string documentationSection = "summary") { var methodDocumentation = symbol.GetDocumentationCommentXml(); if (!string.IsNullOrEmpty(methodDocumentation)) { var doc = XDocument.Parse(methodDocumentation); var nodes = doc.Descendants(documentationSection).FirstO
