Experimental "namespaceLayout": "nested" feature - status

[ghost]

Hi - I am very keen to use a nested layout for API documentation and have tried setting the "namespaceLayout" value in the "metadata" config section to "nested". This has the desired effect but true to the warning "Nested namespace is experimental and may produce undesired result.", if there are no types in the root of a given namespace, then the nesting fails to operate and the traditional individual namespace layout is shown.

Can I ask what the status of this feature is please? Should I raise the above as an issue?

Whilst considering API TOC, I note that Microsoft Learn operates a flat TOC for .NET types (i.e., omitting namespaces). Are there any plans to provide this capability within DocFX?

[yufeih]

It did seem that nested namespaces got a few bugs in certain edge cases. @NanoBob, are you still willing to contributing fixes?

Learn comes with a dedicated API browser page that lists all the namespaces, is this something folks generally wants?

[VaclavElias]

I like it personally 😃

[ghost]

For my part, it wasn't so much the browser page I was after as this form of TOC/layout, without the namespace breakout, which for small-medium sized APIs seems more appropriate:

[NanoBob]

I am definitely willing to contribute fixes @yufeih.

@paytools-master, could you confirm if my understanding of your issue is correct:

Let's say you have the following:

- namespace Foo
  - namespace Foo.Bar
    - Type1 
    - Type2
  - namespace Foo.Bar2
    - Type 3
    - Type 4

Would this be the situation where it goes wrong?

And the following would work correctly:

- namespace Foo
  - Type 5
  - namespace Foo.Bar
    - Type1 
    - Type2
  - namespace Foo.Bar2
    - Type 3
    - Type 4

[ghost]

Many thanks @NanoBob. That's exactly right - your second example works fine, your first example does not.

Related (at the risk of scope creep here), when the nested items (Type1, Type2 in your example) are shown, they get assigned a smaller font - I checked and there is no "level3" style assigned for font size in the CSS. I don't think it makes sense for items to have a different font size to the items that sit in the base of the namespace (Type5 in your example).

Much appreciated.