Ability to expand namespaces by default in nested mode

[ghost]

I am currently using release 2.65.3 with 'nested' layout to some success, thanks in part to @clement-or's helpful issue resolution (see issue #8540).

However, when you go to the 'Api Documentation' home page, you see just the very top level namespace, which looks very sad all on its own. It would be much better if this top level namespace were expanded by default to show all the second level namespaces. (In an ideal world, it would be possible to specify which level to expand to.)

Does anyone have any idea how to implement such a feature, or perhaps this is a spare-time job for the ever-helpful @NanoBob that fixed up nesting most recently?

(If anyone can give me any pointers, I'm more than happy to knock together a PR.)

[moonymachine]

I accomplished this by manually customizing the toc.yml file that gets generated in my api folder during the metadata command. I have separate json files for just metadata.json and build.json instead of docfx.json to run whichever commands I need as I work. So, after I run just the metadata command, then I manually overwrite the toc.yml file that was generated in the api folder. Then, I run the build command and my table of contents is all customized just the way I like it, without having to make separate namespaces or anything.

The downsides are that I have to do this step in between metadata and build. There is probably some way to automate all of this, but I'm just doing it by hand for now. Also, it is error prone. Whatever I manually specify in the explicitly overwritten toc.yml file is what is displayed, regardless of code changes. If I create new classes I have to modify my overwrite toc file manually.

So, because the toc.yml file is overwritten every time I run the metadata command, I keep my custom file in a separate location, outside of the api directory, saved as just a .txt file so it doesn't accidentally get picked up by glob patterns. One problem with that is that I have to be very careful that tabs don't accidentally get inserted instead of spaces and break the yml format. I use Notepad++ and have whitespace visible so I can easily see if this is the case. I have both files open in Notepad++ and after I run the metadata command I just go into the text editor and copy all from the custom txt file and paste all into the generated toc.yml file. Voila! My custom table of contents is now displayed. (After running docfx build.json --serve)

So, to answer the original question. How do you expand the namespace by default? Use the expanded property in your custom yml file. Here is an example of mine. I have the first leaf node page specified for each level of the sub directory foldouts for my table of contents because that helps with the default template, so that if you click on any of the sub section headers it takes you to a relevant page. However, that's not necessary for the modern template the way I have it displayed now. I'm just particular like that, just FYI.

items:
- name: Switchboard
  uid: Switchboard
  expanded: true
  items:
  - name: Core
    uid: Switchboard.DynamicQueue`1
    expanded: true
    items:
    - name: Collections
      uid: Switchboard.DynamicQueue`1
      items:
      - name: DynamicQueue<T>
        uid: Switchboard.DynamicQueue`1

Notice the expanded: true property.

[ghost]

@moonymachine Many thanks for this - just the ticket!

I will probably produce a small tool to process the toc.yml file in between the metadata and the build steps, so it can be run on every build. I'll publish the repo - if you have relatively simple requirements, I would be happy to add your requirements in with my own - let me know if that would be of interest.

(I note that it is possible to add plug-ins to Docfx, but I want something that is really simple to build and maintain, and plug-ins seem at first glance unnecessarily complicated.)

[moonymachine]

I could certainly find that useful if you find a better work flow. I also just thought I would mention that I converted my custom toc file back to yml instead of txt. That way it handles the formatting rules better. I just made the files section of my build.json file more specific to exclude it from the build.

[moonymachine]

Also, I just noticed this other discussion #8662 that points out that you do not have to create separate json config files. You can have one docfx.json file and then just call docfx metadata docfx.json, then docfx build docfx.json --serve and it will only run the appropriate command with the relevant config settings from that file.

[ghost]

Quite so. The docs aren't so clear (I'm trying to improve them in my spare time).

Let me know if you have specific requirements for toc.yml patching - I've made a start but nothing decent enough to publish yet.