6

I'm looking to create a central repository for all of our published API documentation using DocFx. I have documentation auto-generated via my build (using TFS) and published through my release (using Octopus) just fine for multiple individual sites. However, I'm wanting to pull it altogether in one location. The thinking is that through a parent site you could filter content in any of the individual sites without having to drill down into them. Do you have a recommendation on how to do this?

Also, within this same documentation repository I want to provide the capability to search by all of the meta data (project-level documentation) across the hundreds of projects in our portfolio. This will give our BA, DEV and QA teams easier access to what all our systems do. I like the "filtering" capability built into DocFx, but I'm wanting full-text search across all of the meta data. Do you have a recommendation for this functionality as well?

Scott Benners
  • 61
  • 2
  • DocFX uses https://lunrjs.com for search, you could proably extend it in a way so that search works across all "subsites". – bitbonk Aug 02 '17 at 11:42
  • Sorry for the spam, but are you able to answer my DocFx question here: https://stackoverflow.com/q/52119519/248965?sem=2 ? I read your comments on Chris Mason's Documentation in a DevOps World article and it looks like you have done what I am struggling to do! Thx. – Laurence Aug 31 '18 at 16:36

2 Answers2

9

To change the location of the docfx output, edit the docfx.json file and specify the dest value. By default it is "dest": "_site". For more formatting guidance, reference: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html.

Regarding full-text search, that is possible by simply ensuring the ExtractSearchIndex post-processor is invoked (in order to generate an index.json file of keywords) and that the global _enableSearch value is set to true in the docfx.json file. A snippet from that file would look like: 

"postProcessors": [ "ExtractSearchIndex" ],
"globalMetadata": {
  "_enableSearch": "true"
}
Ben Drake - MSFT
  • 171
  • 2
  • 8
1

For your first question:

I think what you expect is like the .NET API Browser. The source code behind this page is not open to public, so you need create this page by yourself, through collecting xrefmap.yml from multiple sites, and extract the needed data into this page.

For your second question:

DocFX uses Luna to scan all the output files and generate an index file called index.json for later search use. In your case, you should want to limit the search scope only in the metadata you defined. This is also not supported by DocFX by default. You can also use Luna in your central place to search these meta. You can create your specific index.json for each project first, and the cental place to collect them for the search page.

Yuby
  • 808
  • 7
  • 19