Is there any way to make the API docs TOC so that it can list Projects and then Namespaces? (i.e. multi level)

[Shazwazza]

trafficstars

DocFX Version Used:

v2.23.1

Template used: (default or statictoc or contain custom template)

custom template

Steps to Reproduce:

N/A

Expected Behavior:

N/A

Actual Behavior:

When generating the docs, the TOC listed is every namespace in every project built which can be a very long list. Instead we'd like to have it list by Projects or 'Package' and then by namespace.

As I'm writing this it occurred to me that I can almost achieve this by specifying multiple entries under the "metadata" of the docfx.json (since it's an array) and can have one entry per project. This essentially generates separate 'sites' per project and then i can create my own toc.yml file to link to each one.

But... a problem I'm seeing with that is that if the same namespace is used between projects, then there are UID issues since a namespace is unique which means that the TOC entry for that namespace in one project will end up linking to the last project specified in the docfx.json file where that namespace also exists. (hope that makes sense, if not I'm happy to post a video or similar)

Any pointers would be much appreciated

[Shazwazza]

Seems I have this mostly working by ensuring i don't have overlap of the same namespaces between projects in the code (but would still be nice to figure that part out), now the issue is the breadcrumb does't work.

here's an example of what I've got in my docfx.json for the 'multiple projects':

  "metadata": [
    {
      "src": [
        {
          "files": [
            "Lucene.Net/Lucene.Net.csproj",
            "Lucene.Net.Misc/Lucene.Net.Misc.csproj"      
          ],
          "exclude": ["**/obj/**", "**/bin/**", "_site/**", "**/Lucene.Net.Test*/**"],
          "cwd": "../src"
        }
      ],
      "dest": "api/Lucene.Net"
    },
    {
      "src": [
        {
          "files": [
            "Lucene.Net.Queries/Lucene.Net.Queries.csproj"
          ],
          "exclude": ["**/obj/**", "**/bin/**", "_site/**", "**/Lucene.Net.Test*/**"],
          "cwd": "../src"
        }
      ],
      "dest": "api/Lucene.Net.Queries"
    }

This outputs to 2 sub folders as expected. Now to link to those, I have this folder structure:

/api/index.md -> This is just a normal markdown doc file /api/toc.yml -> This is my custom TOC to link to the projects built

the toc.yml looks like (for example):

- name: Lucene.Net
  href: Lucene.Net/
- name: Lucene.Net.Queries
  href: Lucene.Net.Queries/

Here's what the index.md page looks like with the toc and breadcrumb which is fine:

When I click on one of those items i get which is missing the first breadcrumb part

I must be missing something obvious?

[vicancy]

Hi @Shazwazza , try changing your toc.yml to

- name: Lucene.Net
  href: Lucene.Net/toc.yml
- name: Lucene.Net.Queries
  href: Lucene.Net.Queries/toc.yml

this is the syntax to include another toc http://dotnet.github.io/docfx/tutorial/intro_toc.html#link-to-another-toc-file

[Shazwazza]

Thanks @vicancy , that's interesting, it works but not quite in the way that i was intending. This results in a 3 level TOC:

What I'm trying to do is have the "Lucene.NET API Docs" page list the 'packages' only (i.e. Lucene.Net, Lucene.Net.Queries, Lucene.Net.Analysis) which is just a one level TOC. When any of those are clicked it goes to that package page and it's TOC is a 2 level toc with the packages namespaces and classes. This means the TOC is a bit less cluttered and the user can use the breadcrumb to navigate back to the packages page.

Maybe I am trying to do something that is just not supported?

[vicancy]

Not supported for now. Currently breadcrumb is pure client js, and when the package page is loaded, the tocpage info is lost. This feature can be supported when breadcrumb is generated by template.

[Shazwazza]

Thanks for the info.

I suppose I could make this work if I hijacked the javascript that creates the breadcrumb (either based on passing a query string to the next page or looking at the Uri path)?

If i have time i'll give that a try

[dario-l]

Thanks to that issue I can now running my docs without merge command which is not working. @Shazwazza Thank you, thank you, thank you very much. :)

[achikhv]

Having the same issue with the namespaces with same name in different projects. Only I can not rename because it would be a major breaking change. Is there any solution to generate unique UIDs for the types with equal names?

[Shazwazza]

Just going to revisit this one, still the same issue today when there are the same namespaces between projects. Does anyone know a solution to that? Even if it involves some sort of manual coding/work?

[JimBobSquarePants]

Can someone please reply to @achikhv and @Shazwazza here. This is a common pattern among libraries distributed across multiple projects and a major blocker.

[Shazwazza]

The main issue here is the way docfx produces UID's which is based purely on the namespace and the class name. In these cases, the main problem is the namespace since there can be the same one between projects. This results in odd things because there's now duplicate UIDs in the project but you'll only get one produced as the output so you can only link to one. Don't think there's any way around this from looking at the code.