dpvreony

Using DocFx as the Document Generation Toolset in a downstream repository.

TLDR: The sample repository is available at: https://github.com/dpvreony/article-docfx-downstream.

Introduction

DocFx is a powerful document generation tool for the .NET ecosphere. It natively works with the XMLDOC of C# and can be embedded into a build chain rather easily. The challenge is if you want to be building and managing the article and concept documentation independently of code changes. For example you want to clarify something in a set of instructions, typically a build chain will build + deploy both the application\ library and the documentation.

An alternative process by isolating the docfx project

You can use either a separate repository (how microsoft docs work) or a detached git branch (which is the way the github gh-pages branch documentation feature works).

Assumptions before you start

  • You're publishing a nuget package for a library.
  • You're producing code documentation and including it in the nuget package.
  • This article is going to use nucleotide as the example. You may want to follow along, or use your own project.

Getting started

  1. Create a repository.

    Template Available : The sample repository can be used as a template. This will let you skip steps 1, 2, 5 and 6 so you can follow along and just tweak the necessary files and processes.
    * Create a new repository * Place a Visual Studio .gitignore file * Choose your license (if you desire) * Clone the repository locally
    For further information on setting up repositories on github check out the github hello world guide. To understand some of the details around github pages check out the Getting started guide.
  2. Create a docfx project.

    * Create a blank solution in a src subdirectory of the repository * Create a netcore library project named docfx * Add the DocFx nuget package to the project.
    For more information on DocFx check out the getting started tutorial.
  3. Verify the build process works by starting the site up locally.

    From a Developer Command prompt in solution run the following (assuming the current directory is the repository src folder) `docfx serve docfx\_site` In the console you should see a success message stating what port the site is available on. ` SOME BLURB HERE ` And you should be able to browse to the site and see something that looks like: SOME IMAGE HERE
  4. Add references to the upstream nuget packages.

    Unfortunately it's not as simple as **just** adding your documented packages as a PackageReference to a C# project (.csproj) file because by default the packages are no longer restored into a packages folder of the repository. So we have to do some work of our own. That said, to allow dependency management tools such as Dependabot to do their work of updating references to upstream dependencies we will take advantage of a C# project!
  5. Create a Build event to retrieve the xmldoc from the nuget packages.

    TODO.
  6. Configure the docfx script to process the xml from the nuget packages.

    TODO.
  7. Configure the repository for Continous Integration and Deployment

    TODO.
  8. Configure the repository to track changes to the upstream nuget packages

    By using a C# project with package references. You're already a good way down the road to being able to automate this. In this example I will use Dependabot but there are other dependency management tools available, or you can opt to manage it via your own process. One of the easiest ways to do this to take an existing dependabot yaml config file and place it at the root of your git repository. You want it to look something like this. ``YAML {SOME CODE HERE} ``

References

Solidly Stated: Edge Windows 10 can't reach localhost sites (2017) https://solidlystated.com/software/edge-windows-10-cant-reach-localhost-sites/ (Accessed 2021-02-28)
Article Status Draft
Article Version 0.1
First Written Wednesday, January 20, 2021
Last Revision Sunday, February 28, 2021
Next Review Friday, May 28, 2021
License MIT