1

I need your guidance...

Given that an organization may have multiple products in various repositories, and probably many documentation repositories, how to integrate everything in one "docs.acme.com" site ?

For example: 3 products: X, Y and Z, and Z has multiple repos. Each have their own /docs.

productX.git

  • /src/ sln + *.csproj
  • /docs/*

productY.git

  • /src/ sln + *.csproj
  • /docs/*

productZ.core.git

  • /src/ sln + core.csproj
  • /docs/* productz.wpf.git
  • /src/ sln + wpf.csproj
  • /docs/* productz.web.git
  • /src/ sln + wpf.csproj
  • /docs/*

Some Teams even have a conceptual docs repo.

TeamFoo.git

  • /docs/*

And the "parent" repo

docs.acme.git

  • /docs/*

The result (if we mimic learn.microsoft.com):

  • docs.acme.com/
  • docs.acme.com/products/
  • docs.acme.com/products/productX/
  • docs.acme.com/products/productY/
  • docs.acme.com/products/productZ/
  • docs.acme.com/products/productZ/core/
  • docs.acme.com/products/productZ/wpf/
  • docs.acme.com/products/productZ/web/
  • docs.acme.com/teams/foo/
  • docs.acme.com/teams/bar/

How is this possible ?

If each repo/docs have their own docfx.json, then each _site compiled will be treated as a "parent site" which is not true.

The closest I've been so far, is for each child docs to have a stub index.md and toc.yml and reproducing the "target folder structure", and have one "parent build" that includes as reference the child repos and copies their relative folders.

It works but is not an efficient nor elegant solution.

Requirements:

  • as a "product" developer, when I run docfx serve, I can validate that the docs look good.
  • as a "corporate docs" integrator, the parent and children docs work/look as one.
  • as a "contributor", when I click on "Contribute to this Doc", I get to the right repo/file
Patrice Calvé
  • 674
  • 6
  • 12
  • Did you have any success with this? We’re looking for the same solution. – APW Feb 16 '22 at 21:25
  • Not much. The closest I've been requires a lot of "involvement" from everyone. Basically, each "product" (in their repos) has a "fake main root" (docfx.json, index.md, toc.yml) and they put their product related stuff in a subfolder. This makes it possible for them to run/test locally. At build time, they publish their product sub folder as "build/pipeline artifact". The main doc site has no clue of the children products, except for the main site build/pipeline which references each product pipeline, injects their content during build. Naming convention is important. – Patrice Calvé Feb 20 '22 at 13:28
  • I forgot to mention, I even created a "Docs Helper" PowerShell module to help teams init a new docfx setup for their product, including auto-generating the docfx.json, fake index.md/toc.yml, an Azure DevOps yaml pipeline (with the proper naming convention expected by the main site), downloads a copy of the main site's custom docfx template, downloads the docfx.console nuget package if not found. This makes the docfx adoption a bit better. DocFx is not an easy sell, I'm currently looking at using Wikis as "authoring tool" which would be leveraged by the main build. – Patrice Calvé Feb 20 '22 at 13:34
  • Interesting. I am in the processes of creating webapi CI process to handle the bulk of the *stitching* work and like you a helper script to setup new repos. Good luck. – APW Feb 22 '22 at 12:27

0 Answers0