How can I add .NET namespace information in DocFX

Question

The title says it all ...

In Sandcastle Help File Builder we added the NamespaceDoc class to each namespace to create namespace documentation.

How do we to the same using DocFX?

Answer 1

Here's how I did it:

1. In the root folder of your documentation project, add a folder named namespaces.
2. Update your docfx.json file to include markup files added to the namespaces folder. You need to update the overwrite property in the build section. It will look something like this:

    "overwrite": [
      {
        "files": [
          "apidoc/**.md",
          "namespaces/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],

3. Create a markdown file in the namespaces folder for every namespace you want to add documentation to. It is probably best to name these files the same as the namespace.

   The files should have a YAML header with a UID that matches the namespace's name. The summary: *content line tells docfx to overwrite the summary of the namespace with the contents of this file.

   The rest of the page is standard markdown that will become the namespace's summary. For example:

   ---
   uid: My.Groovy.Namespace
   summary: *content
   ---
   The My.Groovy.Namespace namespace contains a bunch of classes and interfaces.

Answer 2

There isn't a way to add it directly in source code. You can use overwrite files to add summary for namespace type.

Answer 3

I'm probably extremely late to this question, but i faced a similar problem and the solution i found invovles modifying docfx from source and adding helping classes, much like Sandcastle's solution.

Disclamer:

I do not claim that the solution i'm showcasing is programmatically stable, safe or even correct. I do not claim that this solution will work in any scenario or for any use. I only verify that, for me, it worked perfectly fine, even though i recongize it's just a fast-put-up workaround.

Steps :

1. I downloaded the source code of docfx from their github's releases page (2.59.2, as of today)

---

2. After extracting the solution, I opened the file docfx-2.59.2\src\Microsoft.DocAsCode.Metadata.ManagedReference\ExtractMetadataWorker.cs

---

3. The class implemented within this file contains a method named GetMetadataFromProjectLevelCache that, at some point, extracts the metadata from the referenced project in a tree form.

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key); // THIS line
   // [...]
}

---

4. After this line, I appended the following line containing a method which I also had to implement.

private Tuple<MetadataItem, bool> GetMetadataFromProjectLevelCache(IBuildController controller, IInputParameters key){
   // [...]
   projectMetadata = controller.ExtractMetadata(key);
   ExtractNamespaceDocumentation(projectMetadata); // THIS line
   // [...]
}

---

5. The implementation was the following:

private void ExtractNamespaceDocumentation(MetadataItem node)
{
    // Terminal nodes are not of our interest in any case
    // Even if it's a namespace, it does not contain documentation
    if (node.Items is not { Count: > 0 }) return;
    
    // If it is namespace
    if (node.Type == MemberType.Namespace)
    {
        // Get (if any), the child that is class and is named "_NamespaceDoc"
        var doc = node.Items.FirstOrDefault(x =>
            x.Type == MemberType.Class && x.Name.Split('.').Last() == "_NamespaceDoc");

        // If we didn't found such class, the namespace does not contain documentation.
        // Leave and don't go further.
        if (doc is null) return;

        // Else, assign the class' Summary and remarks to the Namespace and remove the class from the tree.
        node.Summary = doc.Summary;
        node.Remarks = doc.Remarks;
        node.Items.Remove(doc);

        // job finished for this namespace, we do not want to go further down the tree.
        return;
    }

    // For non-namespace intermediate nodes (IE assembly nodes), visit the children.
    foreach (var child in node.Items) ExtractNamespaceDocumentation(child);
}

---

6. Lastly, I compiled the solution and, by using the newly created docfx.exe located at docfx-2.59.2\src\docfx\bin\Debug\net472, i was able to detect all classes named _NamespaceDoc and use their <summary> tags to fill the namespaces they resided.

---

For the record, i decided to create a new .cs file at the root of my project to contain all _NamespaceDoc classes, so it would be easier for me to disable the whole file when i want to release the project. This file looked like this:

namespace RootNamespace
{
    /// <summary>
    /// Documentation for the Root Namespace
    /// </summary>
    public static class _NamespaceDoc { }
}

namespace RootNamespace.SubFolder
{
    /// <summary>
    /// Documentation for the Root Namespace's `SubFolder` Sub-Namespace.
    /// </summary>
    public static class _NamespaceDoc { }
}

// [...]

Hopefully, this may help other fellows seaking for such solution, or even the docfx devs and contributors to implement this feature more reliably.

---

Update:

For more info about this approach, I've started a discussion on docfx's github repository