DocFX documentation

[bcrosnier]

I've been working on a DocFX documentation project, currently available in preview on https://bcrosnier.github.io/CK-ActivityMonitor/.

It contains the API documentation, a getting started guide, and an overview of some advanced features. If this proves interesting, I can try submitting a PR here - it's on https://github.com/bcrosnier/CK-ActivityMonitor/tree/feature/docfx in the meantime.

Until then, there's the question of where to push the docs. GitHub Pages looks ideal for static sites like the one generated by docfx, but requires some wizardry to deploy in an automated manner (namely creating a commit on a different branch from the commit that's being built). But as far as I know, it has been done before.

Handling different versions (with one site having multiple versions of the documentation on it) also requires some wizardry, but is possible using Jekyll, which is GitHub Pages, and iframes, unless there's a better way. This can be done later, as my objective for now is to put at least one documentation online.

To-do:

• Prepare project
• Write intro pages
• Replace CK-Text page title and header by CK-ActivityMonitor
• Integrate docfx with CodeCakeBuilder
• Add version and license to doc
• Automate doc update

[olivier-spinelli]

Great!
I have a question regarding the links in the documentation between different projects. Can the hyperlinks magically target the "other" documentation?

[bcrosnier]

They could, but they need to have the generated xrefmap.yml (which is basically an index) from said other project, unless they are part of the same DocFX website. They can also be written by hand.

This is basically what the MSDN xref package does with the BCL types, which will link instances of e.g. System.String or System.Int32 from the DocFX-generated site to the corresponding MSDN pages.

More info is available on the Links and Cross References page of DocFX.