[WIP/Discussion] DocFx example for Serilog org

[merbla]

Following on from discussions in serilog/serilog#1164.

Existing landing page remains intact and uses subfolder docs for output.

Basic Workflow for DocFx

1. Install DocFx.
2. Run Make command make build-docs. This will do the [following]:(https://github.com/serilog/serilog.github.io/pull/5/files#diff-b67911656ef5d18c4ae36cb6741b7965)
   • Clean src
   • Shallow clone of repositories (Serilog, Sinks etc.)
   • Build metadata
   • Build documentation, site will be published to docs.
3. Run make serve-docs to serve content at http://localhost:8080.

Example site structure

├── docs
│   ├── api
│   │   ├── serilog
│   │   ├── serilog-aspnetcore
│   │   └── serilog-sinks-console
│   ├── fonts
│   ├── howto
│   └── styles
├── images
├── img
├── js
├── theme
└── index.html

More questions...

1. How to trigger builds? Do other repositories trigger? Nightly builds?
2. How to brand the site for consistency with Serilog. Custom templates are possible however it seems lacking in extensibility

After working with Hugo for sometime, I found DocFx cumbersome and light on features.

[merbla]

Example pages for reference.

It appears some UIDs will clash given the namespace usage of Sinks and configuration methods. I am sure there would be some work arounds.

[nblumhardt]

👏 I can't speak to the DocFx vs Hugo question (as first committer I think you own that choice :-)) but this looks pretty impressive for a starting point!

Nightly builds seem like the best bet, we'd be constantly churning it otherwise.

Happy to be signed up for whatever I can usefully contribute, just give the word! (Or let me know a day we can get around a cafe table and hack at it :-))

[AraHaan]

I think this could help with nightly builds as well too (for those who prefer installers for shared framework versions to serilog and all of it's supported sinks). Sadly I would like to ask if the serilog org can take it on (I have set up dependabot so pr's should just be as easy as merge them every now and then) https://github.com/Elskom/Serilog-Installer (It uses dotnet/arcade however).

However it will need to have a few updated files for the installer as well, it got references to one of my other shared frameworks in the installer's text while some others are from the dotnet/runtime repo as I do not know any language except english (those would also require changes). Also the purple theme and the icon would need to be changed to the serilog icon and to red to match serilog more.

Why a shared framework you ask? Because sometimes people like me want to share their serilog dependencies with all of their projects, however in .NET 6+ dotnet store was made to no longer work making shared frameworks the only way to achieve that in a way that does not copy the serilog binaries into our projects output directories. I wanted to do this because then I could leverage RollForward to then roll forward on serilog updates just from installing an updated copy using the installer which is afaik much easier to manage than updating the nuget packages manually in all of my projects plus the disk space would be used more if I done that over the shared framework option anyway. The shared framework I made currently supports .NET 6 only, I am looking into a way where if the user's application targets .NET 7 (the latest patch on that) to somehow have the shared framework want to use that as well. Fixed, the issue was that I needed for it to specify Major in the shared framework itself so it will use .NET 6 when application targets .NET 6, .NET 7+'s runtime otherwise.