Migrate docs site to docfx

[nzdev]

What?

Basic migration of the existing docs site to docfx.

Why?

Improved docs experience.

• Easier to read
• Easier to contribute.
• Improved navigation within a page
• Autogenerate API docs
• Content/API Search
• Use .NET for docs, simpler to run locally for .NET developers

How?

Created new docfx project in docs folder.
Set up docfx theme.
Migrated existing docs to docfx syntax in the /articles dir.
Configured docfx for search, improve this doc.
Configured docfx for API Docs generation.

Missing features?

• Correctly sized Examine logo.
• Social links at the bottom of the page as I'm unsure how to add @Shazwazza
• Version Tabs (Converted to subheadings), V1/V2 documentation split from V3
• 404 page
• Redirects for existing docs links

How to test?

Install docfx
cd to /docs
In a command prompt run

docfx --serve

How to build?

Example for Azure DevOps

- task: DotNetCoreCLI@2
  displayName: Build Examine
  inputs:
    command: 'build'
    arguments: '--configuration $(BuildConfiguration)'
    projects: '**/*.csproj'

- powershell: |
    choco install docfx -y
    docfx doc/docfx.json
    if ($lastexitcode -ne 0){
      throw ("Error generating document")
    }
  displayName: "Build Documentation"

Example of docfx on github pages https://github.com/dotMorten/NmeaParser/blob/main/.github/workflows/ghpages.yml

Homepage

API Doc

Search

V3 Article

V1 / V2 Article

https://nzdev.github.io/Examine/index.html

[nikcio]

@nzdev For navbar & favicon I found:

"_appLogoPath": "navlogo.svg",
"_appFaviconPath": "favicon.ico"

That can be used to configure it. But docfx is missing a bunch of SoMe meta tags that the existing doc site has. Furthermore the styling in the theme as is properly needs to be looked at for this to work properly. Looking very shortly at this PR I found the following:

• Navbar icon isn't sized after the navbar height. This means that if you add an image that is not the correct size it will overflow or align incorrectly.
• If the Navbar image is an svg as the default logo the hover effect will make it all white.

And as a last note the test projects should properly be excluded from the API documentation. 😅

[nzdev]

Thanks @nikcio Worked around the logo and filtered the API docs.

[nzdev]

May be cleaner to just have v3 in docfx and have the v1/v2 on a prefix.

[nzdev]

I've split out the v1 / v2 docs into their own section so that any api usages can be linked to the api docs.

[nzdev]

Linked up a number of code references to the API docs.

[nzdev]

I haven't tried this out and maybe there are other ones but would be good to get a GitHub actoin in place to publish these so we can see the live version. https://github.com/marketplace/actions/docfx-action

I've given this a go. But I'm very stuck.

[nzdev]

Finally some success https://github.com/nzdev/Examine/actions/runs/4143575564/workflow https://nzdev.github.io/Examine/index.html

[Shazwazza]

@nzdev was trying to build these locally, I've done:

Install docfx
cd to /docs/v2
In a command prompt run

docfx --serve

It builds the docs and serves them but it doesn't build the API docs and shows a ton of errors/warnings. Should this 'just work' or am I missing some conifguration?

Also, I found this page about publishing to GitHub pages: https://dotnet.github.io/docfx/#publish-to-github-pages I wonder if that would make things a little more flexible?

[nzdev]

I think it depends on the version of docfx and what msbuild is being used. Needs to use a visual studio msbuild.

[Shazwazza]

Pretty sure it's this issue that I'm seeing dotnet/docfx#8465

[nzdev]

I'd say so @Shazwazza . We had this as well on an earlier version. See https://dotnet.github.io/docfx/docs/dotnet-api-docs.html?q=msbuild#generate-from-projects-or-solutions as one possible workaround

[nzdev]

See also dotnet/docfx#8136 (comment). Which version of docfx are you using? I use 2.59.4.0 without issue with VS2022 and VS2019 Build Tools installed.

[Shazwazza]

Just updated to latest docfx from '2.62.1' to version '2.62.2'. So it must have been a bug they fixed. Builds great locally now.

Now to figure out the rest :)

[Shazwazza]

Well I got it 'working' to deploy docfx to v2 sub folder but GitHub pages normal jekyll builds and our custom build aren't compatible with each other because they overwrite each other (more or less).

I'll work on updating the new docs theme, colors, etc... and just make that the main docs :)

[Shazwazza]

Alternatively i can manually build the original jekyll docs with this https://github.com/actions/jekyll-build-pages/blob/main/action.yml but seems like too much effort for an interim thing.

[Shazwazza]

@nzdev this is live now :) https://shazwazza.github.io/Examine/

Thanks so much this is fantastic :)

The branch for these docs currently are in the feature/docfx branch in the Examine repo.

[nzdev]

Awesome @Shazwazza . I like the header theme.