Dokumentation erstellen mit MkDocs

Ich liebe Markdown. Es ist einfach zu schreiben und man bekommt ein schönes Resultat.
Darum habe ich mich entschlossen viele der Dokumentation welche ich schreiben muss darf, auch in Markdown zu schreiben.

Hab mich bei der zweiten Auflage meines Buches dazu entschieden auch eine kleine Website zu machen. WordPress oder ein anderes CMS war für den Anwendungsfall einfach zu groß.

Zufällig bin ich dann mal über MkDocs gestolpert. Dies generiert aus Markdown files schöne Websites die sich super für Dokumentationen eignen. Bekannter dürfte Jekyll sein, aber das ist wieder zu groß für so kleine Dokus.

Da ich auf der Seite die ganzen Beispiel vom Buch darstellen wollte und natürlich zu faul bin das alles zu kopieren… Hab ich mir einfach ein kleines C# Programm erstellt, welches mir die Arbeit abnimmt.
Es generiert Pro Kapitel-Ordner und Script-Datei eine Markdown-Datei mit Überschriften usw.
Zusätzlich wird auch noch die Übersicht generiert.
In der Debug-Konsole lass ich mir auch noch gleich die Menüpunkte ausgeben, welche dann in der YML-Datei von MkDocs landen.

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;

namespace DocuCreator
{
  class Program
  {
    static void Main(string[] args)
    {
      // Output
      string outputDirectory = @"\\Mac\Home\Documents\GitHub\EplanElectricP8Automatisieren.V2.Writing\Documentation\Website\docs\scripts";
      if (Directory.Exists(outputDirectory))
      {
        Directory.Delete(outputDirectory, true);
      }
      Directory.CreateDirectory(outputDirectory);

      // Overview
      Console.WriteLine("- 'Übersicht': 'scripts/Overview.md'");
      string fileNameOVerview = Path.Combine(outputDirectory, "Overview.md");
      StringBuilder sbOverview = new StringBuilder();
      sbOverview.AppendLine(); // Needed for Encoding problem
      sbOverview.AppendLine("**Übersicht**");
      sbOverview.AppendLine();
      sbOverview.AppendLine("---"); // Devider line
      sbOverview.AppendLine();

      // Folder
      string path = @"\\Mac\Home\Documents\GitHub\EplanElectricP8Automatisieren.V2.Writing\Data\Code\EPLAN Scripting Project";
      var directories = Directory.GetDirectories(path, "*_*").OrderBy(obj => obj).ToList();
      foreach (var directory in directories)
      {
        string directoryName = new DirectoryInfo(directory).Name;
        string directoryNameWithSpaces = directoryName.Replace("_", " ");
        var directoryNameWithoutUmlauts = directoryName
             .Replace("ä", "ae")
             .Replace("ö", "oe")
             .Replace("ü", "ue")
          ;

        // Overview
        sbOverview.AppendLine($"### [{directoryNameWithSpaces}]({directoryNameWithoutUmlauts}.md)");

        // Files
        StringBuilder sb = new StringBuilder();
        sb.AppendLine(); // Needed for Encoding problem        
        string header1 = $"**{directoryNameWithSpaces}**"; // Main header
        sb.AppendLine(header1);
        sb.AppendLine();
        sb.AppendLine("---"); // Devider line
        sb.AppendLine();

        var files = Directory.GetFiles(directory, "*.cs", SearchOption.TopDirectoryOnly).OrderBy(obj => obj).ToList();
        foreach (var file in files)
        {
          AddFile(file, sbOverview, directoryNameWithoutUmlauts, sb, files);
        }

        // Write file
        string outputFile = Path.Combine(outputDirectory, directoryNameWithoutUmlauts + ".md");
        File.WriteAllText(outputFile, sb.ToString(), Encoding.UTF8);
        Console.WriteLine($"- '{directoryNameWithSpaces}': 'scripts/{directoryNameWithoutUmlauts}.md'");

      }

      // RemoteClient
      Console.WriteLine("- 'RemoteClient': 'scripts/RemoteClient.md'");
      AddFileRemoteClient(sbOverview, outputDirectory);

      // Write Overview
      File.WriteAllText(fileNameOVerview, sbOverview.ToString(), Encoding.UTF8);
    }

    private static void AddFileRemoteClient(StringBuilder sbOverview, string outputDirectory)
    {
      var fileRemoteClient = @"\\Mac\Home\Documents\GitHub\EplanElectricP8Automatisieren.V2.Writing\Data\Code\EPLAN Remote Client\Program.cs";
      string outputFile = Path.Combine(outputDirectory, "RemoteClient.md");

      sbOverview.AppendLine($"### [RemoteClient](RemoteClient.md)");

      StringBuilder sb = new StringBuilder();
      string header1 = "##### RemoteClient"; // Main header
      sb.AppendLine(header1);
      string lines = File.ReadAllText(fileRemoteClient);
      sb.AppendLine("```csharp"); // Code start
      sb.AppendLine(lines); // Code
      sb.AppendLine("```"); // Code end
      sb.AppendLine();
      File.WriteAllText(outputFile, sb.ToString(), Encoding.UTF8);
    }

    private static void AddFile(string file, StringBuilder sbOverview, string directoryNameWithoutUmlauts, StringBuilder sb,
      List<string> files)
    {
      string fileName = Path.GetFileNameWithoutExtension(file);
      string fileNameWithSpaces = fileName.Replace("_", " ");

      // ReSharper disable once PossibleNullReferenceException
      var anker = fileNameWithSpaces
          .ToLower()
          .Replace(" ", "-")
          .Replace('ä', 'a')
          .Replace('ö', 'o')
          .Replace('ü', 'u')
        ;
      sbOverview.AppendLine($"- [{fileNameWithSpaces}]({directoryNameWithoutUmlauts}.md#{anker})");

      string header2 = $"##### {fileNameWithSpaces}"; // Sub header
      sb.AppendLine(header2);
      string lines = File.ReadAllText(file);
      sb.AppendLine("```csharp"); // Code start
      sb.AppendLine(lines); // Code
      sb.AppendLine("```"); // Code end
      sb.AppendLine();

      // Devider line if not last
      if (!files.Last().Equals(file))
      {
        sb.AppendLine();
        sb.AppendLine("<br>");
      }
    }
  }
}

Alles bisl Quick-And-Dirty, aber läuft super.

Vorteil: Bei jeder Änderung am Script muss ich nur das kurz laufen lassen und die Website ist wieder aktuell. Für künftige Auflagen eine große Erleichterung.