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