Taming DocFx to match SHFB features

[calacayir]

We used SHFB for many years mainly because of its excellent <code> block and NamespaceDoc support and it had been very stable but imho its theme and architecture is a bit outdated. DocFx is great in many ways but it misses some important features that we got used to with SHFB. So I created a new project docfx-plus to enhance DocFx. My aim was to update existing project docs that depend on some SHFB features, without changes to xml comments, to DocFx. Check it out and let me know what you think.

Live Demo - Sample API docs result for our other project DotMake Command-Line.

[StephenHidem]

Outstanding! I like the look and plan on checking it out. Can it run as a Github Action?

[calacayir]

Glad you like it. Yes, you can use it as a Github Action:

Publish to GitHub Pages:

Create a workflow file in your repository, e.g. publish-docs.yml file in .github\workflows folder with these contents:

# Your GitHub workflow file under .github/workflows/
# Trigger the action on push to main
on:
  push:
    branches:
      - main

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  actions: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false
  
jobs:
  publish-docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    - name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 8.x

    - run: dotnet tool update -g docfx-plus
    - run: docfx-plus docfx.json
      # use working-directory for docfx step otherwise codeSourceBasePath is not resolved correctly
      working-directory: docs

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        # Upload entire repository
        path: 'docs/_site'
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

Then enable GitHub Actions for your repository's Pages settings as described here:
Publishing with a custom GitHub Actions workflow

Now whenever you commit, your action will run automatically and publish your docs.

For example, this action is used live here: https://github.com/dotmake-build/command-line/blob/main/.github/workflows/publish-docs.yml
and the docfx.json that was used is here: https://github.com/dotmake-build/command-line/blob/main/docs/docfx.json

[calacayir]

FYI, I am currently working on adding a convert command to docfx-plus which will convert existing .shfbproj projects to docfx.json projects. Especially working on converting MAML files (.aml) to markdown files (.md) which can be rendered and displayed in docfx. This way there will be no need to rewrite conceptual topics for markdown.

[EWSoftware]

@calacayir In your comment above you note your reason for switching to docfx is that the theme and architecture in SHFB are outdated. Being so close to the project, I don't always see its shortcomings and issues with usage unless someone takes the time to report them or asks for a change. Things I do know:

• Needing to use MAML for conceptual content is off-putting to most users. Markdown is now preferred. I get that but haven't had a good way forward that handles the limitations I see with using Markdown for my own projects. A recent comment on another thread has given me some new ideas though and I think I've now got a way to make it workable.
• The presentation style needs work to bring it up to date. I need better handling for the TOC, a better search option, and support for light and dark themes at the minimum. It's on the proverbial list and I want to try to get to it soon.

I'm interested to know what else you see as limitations or what else is outdated in SHFB that make docfx preferable.

[calacayir]

@EWSoftware Yes, the main reason is MAML is hard to write than markdown, especially when you want to update docs. Also SHFB does not support latest <inheritDoc> features in dotnet.

@StephenHidem As promised, I have just released DocFx-Plus v2.0.0 (it was a heavier job than I expected) which adds new convert command to convert/migrate your existing SHFB (Sandcastle Help File Builder) projects completely to docfx projects:

• Project file (.shfbproj) will be converted to docfx.json
• Content Layout files (.content) will be converted to toc.yml
• MAML Topic files (.aml) will be converted to Markdown files (.md)
• Namespace summaries will be converted to overwrite files (.md)
• Other content files like images will be copied
• By default content subfolder will be rebased to docs
  and icons, media subfolders will be rebased to images
  to match docfx conventions.

Sample Outputs

These documentation projects are converted from SHFB to Docfx-Plus:

• Small Earth Technology ANT+ Class Library
• Sandcastle Help File Builder Documentation
• Sandcastle MAML Guide
• Sandcastle XML Comments Guide

[EWSoftware]

@calacayir What inheritdoc features aren't supported? As far as I know there's only two attributes (cref and path) and both are supported.

[calacayir]

I mean for example dotnet now imports <param> tags (or other tags) from the global <inheritDoc> at the beginning so you don't need to put <param> tags for every parameter in the overload:

/// <inheritdoc cref="CliParser.Parse(string)" />
/// <typeparam name="TDefinition"><inheritdoc cref="GetParser{TDefinition}" path="/typeparam[@name='TDefinition']/node()" /></typeparam>
/// <param name="settings"><inheritdoc cref="GetParser{TDefinition}" path="/param[@name='settings']/node()" /></param>
/// <example>
///     <code source="../TestApp/CliExamples.cs" region="CliParseStringWithResult" language="cs" />
/// </example>
public static CliResult Parse<TDefinition>(string commandLine, CliSettings settings = null)
{
    var parser = GetParser<TDefinition>(settings);

    return parser.Parse(commandLine);
}

So <param> for string commandLine in this example is automatically imported.

[EWSoftware]

SHFB's inheritdoc does that too, always has unless they match an element on the inheriting member by cref/name or the parameter names don't match (top-level inheritance rules). I'm not sure DocFX always did. It lagged behind for quite a while with regard to inheritdoc functionality as I recall.