docfx

docFX - Remove namespace prefix in API Reference TOC


I am generating API reference from C# project. The project is part of big solution and has long name convention for assemblies and namespaces, so every namespace in project goes like [CompanyName].[System].[Area].[Module].[...] (e.g. MyBiz.CRM.Sales.Analytics.Persistence.Common and MyBiz.CRM.Sales.Analytics.Persistence.Sql). Since all namespaces in project start with MyBiz.CRM.Sales. and I generate reference for each system and area separately, I want to exclude MyBiz.CRM.Sales. in TOC on left side and only mention it in title/header.

Is it possible in docFX or I need to write custom server side post-build event script?

Thanks in advance


Solution

  • I also had the same problem and solved it by writing a template. The only thing it does is overriding the preTransform hook which you need to specify in a file named toc.extension.js. There I strip the long namespace prefix. As I have a TOC in several layers, I do that recursively. You can most probably hard-code it for the level you need. My code looks as follows:

    exports.preTransform = function (model) {
      // replace recursively the root namespace by ""
      transformItem(model, 1);
      return model;
    
      function transformItem(item, level) {
        if (item.name) {
          item.name = item.name.replace("Some.Very.Long.Namespace.Prefix.", '');
        } else {
          item.name = null;
        }
    
        if (item.items && item.items.length > 0) {
          var length = item.items.length;
          for (var i = 0; i < length; i++) {
            transformItem(item.items[i], level + 1);
          };
        }
      }
    }
    

    Afterwards, I simply specify the own template in addition to the default template in docfx.json which causes the hook to be called. That works as follows:

    "build": {
        "template": [
            "default",
            "/path/to/your/template/folder"
        ]
    }
    

    References: Docfx: How to create a custom template