Organization use of DocFx in a parent-children doc site and multiple separate projects

[patware]

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 ? Documentation can come from many products (conceptual and api) and teams.

Example: 3 products and 1 team

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 docs.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 I'm not sure this is recommended.

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

Note: this question was asked at StackOverflow but didn't get answers.

[ParadiseFallen]

any workaround on this?

[malstraem]

@patware @ParadiseFallen

I'm not sure I fully understood your need, correct me if something is wrong. But I think my experience will help you - at my work i develop internal engine library and produce docs for it through CI pipeline using Docfx.App package. That docs contains one writed section and two generated API sections (so navbar have two separated links for API).

Repo structure looks like:

- ...
- docs
  - api
    -  my-project
      - ...
    - my-project-additional
      - ...
  - articles
    - ...
    - toc.yml
  - MyDocsProject.csproj
  - docfx.json
  - index.md
  - toc.yml
- source
  - my-project
    - MyProject.csproj
    - ...
  - my-project-additional
    - MyProject.Additional.csproj
    - ...
- MyProject.sln
- ...

docfx.json looks like:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "source/my-project/MyProject.csproj"
          ],
          "src": "../"
        }
      ],
      "dest": "api/my-project"
    },
    {
      "src": [
        {
          "files": [
            "source/my-project-additional/MyProject.Additional.csproj"
          ],
          "src": "../"
        }
      ],
      "dest": "api/my-project-additional"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/my-project/**.yml",
          "api/my-project/index.md",
          "api/my-project-additional/**.yml",
          "api/my-project-additional/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
   ...
  }
}

and root toc.yml looks like:

- name: Some Stuff
  href: articles/
- name: MyProject API
  href: api/my-project/
  homepage: api/my-project/index.md
- name: My Project Additional API
  href: api/my-project-additional/
  homepage: api/my-project-additional/index.md

So,

• you have a lot of projects located in different repositories (for example, gitlab)
• each of the projects contains (or could potentially contain) their own documentation
• you want to aggregate all projects on one site

I think you can solve the problem simply by creating a repository in which you accumulate everything you need via submodules and generate documentation. Of course, setting up paths will be more difficult, but it is possible.

[patware]

Thanks for the suggestion @malstraem, unfortunately our scenario is too complex.

We currently have 100+ APIs that are exposed to the docfx site, all in their respective repos and their own pipelines, and they're in different azure.devops.com Organizations and/or Team Products. Plus "Conceptual" sites, and recently added the documentation of PowerShell Modules. It wouldn't scale ;)

Our solution is the following:

• Each API's pipeline generates the documentation (docfx metadata) and the yaml files are included in the pipeline artifacts
• Each PowerShell module pipelines uses a combination of PlatyPS, Mustache and custom scripts to generate the documentation in Markdown form, and publishes the files in the Pipeline artifacts
• The conceptual sites have been migrated to Azure DevOps Wikis (code wikis)
• The main docs repo has the base docfx.json and our template customizations,
• The main docs pipeline has a reference to each of the API pipeline artifact and code wiki repos
• A PowerShell script was created to merge all of these together.
  • Ado Wikis pages are transformed and tweaked into DocFx friendly form
  • Wikis, APIs, PowerShell modules and conceptual sites are "merged" into their corresponding parent's TOC.yml
  • Items are added to the docfx.json proper build sections (content, resource) and in certain cases fileMetadata/_gitContrib.

If you want to check it out, I've created a GitHub repo https://github.com/patware/DocFxHelper for the Merge script.

It's a work in progress, as you can imagine. A script that started as a dozen of lines of code is now more than 2500 lines of code.

The script works. Our site has more than 2000 html files generated.

I recently fixed a bug internally but didn't have to update this repo, I'll find the time this week to change it.

Also, the script makes assumptions that the template requires. I've made those changes in our template, but it's messy and need to review the way it's done.

[malstraem]

unfortunately our scenario is too complex.

Damn more complex i would say 😅, but in fact you have accumulated, it could not be otherwise, nice work.