Skip to content

Publish HTML Documentation #29

Open

Description

@JeremyCaney

The OnTopic Library has a rich collection of inline documentation in the form of XML Docs. This is currently used by Visual Studio for IntelliSense, but not much beyond that.

Ideally, this would be used to generate HTML documentation which would then be published publicly.

Open Questions

  • Library: DocFX?
  • Location: GitHub Pages?

Activity

  1. JeremyCaney commented on Jan 4, 2022

    @JeremyCaney
    MemberAuthor

    The current version of DocFx doesn't yet support C# 10's implicit or global using directives. To mitigate this, we'll need to operate against the compiled assemblies (*.dll), instead of the projects (*.csproj) or source code (*.cs).

    This can be accomplished by setting OnTopic.All as a project dependency on the DocFx project, and then adding something like the following to the docfx.json configuration:

    { 
      "metadata": [{
        "src": [{
          "files": [
            "OnTopic.All/bin/Debug/netcoreapp3.1/**.dll"
          ]
        }]
      }]
    }
  2. JeremyCaney commented on Jan 4, 2022

    @JeremyCaney
    MemberAuthor

    For integrated hosting of DocFx with Visual Studio, we can create an empty ASP.NET Core 6 project, and then setup the WebApplication to support loading default, static documents from the _site folder:

    var builder = WebApplication.CreateBuilder(
        new WebApplicationOptions() 
        {
            WebRootPath = "_site"
        }
    );
    
    var app = builder.Build();
    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.Run();

    This way, we can run the DocFx site directly using the IDE's integration with either IIS Express or Kestrel.

  3. added and removed
    Status 1: RoadmapPlanned for a future, indeterminate release.
    on Jan 4, 2022
  4. added this to the OnTopic 5.2.0 milestone on Jan 4, 2022
  5. JeremyCaney commented on Jan 4, 2022

    @JeremyCaney
    MemberAuthor

    By default, references to the .NET Core Base Class Library (BCL) won't be cross-referenced back to docs.microsoft.com. Per the DocFx documentation, however, this can easily be mitigated by cross-referencing Microsoft's xref service in the docfx.json file:

    {
      "build": {
        "xrefService": [
          "https://xref.docs.microsoft.com/query?uid={uid}" 
        ]
        ...
      }
    }
  6. JeremyCaney commented on Jan 6, 2022

    @JeremyCaney
    MemberAuthor

    Instead of making this part of the OnTopic Library repository, it might make more sense to establish this as a separate repository. This would ensure that:

    1. It could consolidate documentation from OnTopic Library, OnTopic Editor, and the Data Transfer Service, and
    2. Make it easier to update the conceptual documentation independent of the release schedule.

    This can be done by sourcing the XML documentation from the NuGet files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions