Enable watch mode?

[rmannibucau]

Hi,

I'm using docfx programmatically - mainly to have living documentation and generate content before the rendering easily - but to work on the doc I kind of forked the serve mode and added watch mode using a file watcher, is it something which would be worth adding to docfx itself?

Here is my main if it helps:

public static class RenderDoc
{
    private static async Task Main(string[] args)
    {
        var baseDir = Path.GetFullPath($"{AppDomain.CurrentDomain.BaseDirectory}/../../..");
        var docfxConf = $"{baseDir}/docfx.json";

        using var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
        var logger = loggerFactory.CreateLogger(typeof(RenderDoc));

        _RunPreActions(baseDir, logger); // generated content

        await _DoRender(logger, docfxConf); // first rendering to always have _site present

        // is serve+watch mode enabled
        if ((args.Length > 0 && bool.Parse(args[0])) ||
            bool.Parse(Environment.GetEnvironmentVariable("DOC_SERVE") ?? "false"))
        {
            await using var app = _Serve(logger, $"{baseDir}/_site");

            async void OnChange()
            {
                await _DoRender(logger, docfxConf);
            }
            using var watcher = _Watch(baseDir, OnChange);

            await app.WaitForShutdownAsync();
        }
    }

    // this is very custom and could be neat to run custom extension points (Action?)
    private static void _RunPreActions(string baseDir, ILogger logger)
    {
        _GenerateJsonSchema(typeof(Manifest), $"{baseDir}/docs/generated/schema/manifest.jsonschema.json", logger);
    }

    private static void _GenerateJsonSchema(Type type, string output, ILogger logger)
    {
        var jsonSchemaGenerator = new JsonSchemaGenerator();
        var schema = jsonSchemaGenerator.For(type);
        var dir = Directory.GetParent(output);
        if (dir?.Exists is false)
        {
            Directory.CreateDirectory(dir.FullName);
        }
        File.WriteAllText(output, JsonSerializer.Serialize(schema, jsonSchemaGenerator.JsonOptions));
        logger.LogInformation("Wrote '{output}'", output);
    }

    // the interesting part
    private static FileSystemWatcher _Watch(string baseDir, Action onChange)
    {
        var watcher = new FileSystemWatcher(baseDir);
        watcher.IncludeSubdirectories = true;
        watcher.NotifyFilter = NotifyFilters.Attributes | NotifyFilters.Size | NotifyFilters.FileName |
                               NotifyFilters.DirectoryName | NotifyFilters.LastWrite; // or nothing?
        watcher.Filters.Add("index.md");
        watcher.Filters.Add("toc.yml");
        watcher.Filters.Add("docs/**");
        watcher.Changed += (_, _) => onChange();
        watcher.Created += (_, _) => onChange();
        watcher.Deleted += (_, _) => onChange();
        watcher.Renamed += (_, _) => onChange();
        watcher.EnableRaisingEvents = true;
        return watcher;
    }

    private static WebApplication _Serve(ILogger logger, string docBase)
    {
        var url = "http://localhost:8080"; // todo: make configurable?
        var builder = WebApplication.CreateBuilder();
        builder.WebHost.UseUrls(url);
        var app = builder.Build();
        app.UseFileServer(new FileServerOptions
        {
            StaticFileOptions = { ServeUnknownFileTypes = true },
            EnableDirectoryBrowsing = true,
            FileProvider = new PhysicalFileProvider(docBase)
        });
        logger.LogInformation($"Doc available at '{url}'.", url);
        app.Start();
        return app;
    }

    // todo: let output dir be configurable from there and not the docfx.json to align serving with this code
    private static async Task _DoRender(ILogger logger, string directory)
    {
        logger.LogInformation($"Rendering '{directory}'", directory);
        await Docset.Build(
            directory,
            new BuildOptions
            {
                ConfigureMarkdig = p => p
                    .UseAbbreviations()
                    .UseFootnotes()
                    .UseGridTables()
                    .UseBootstrap()
            });
    }
}