Auto-generated index files clash

[GeertvanHorrik]

For API generation, I have multiple assemblies with the same root namespace. This clashes because the index files are created at the root level.

Would you accept a PR that creates the index files in the target directories or can we force the generation of a unique name in a different manner?

For example, in this case:

http://docs.catelproject.com/vnext/Catel.htm

A name like this would solve it:

api-reference-catel-core-catel.htm api-reference-catel-serialization-json-catel.htm

[FransBouma]

I think I need a concrete example. Index files for search or html files? Isn't it possible to generate a folder for the namespace?

[GeertvanHorrik]

This is for the automatic index files (htm). But in theory we would have the same issue if:

/docs/somestuff1/introduction/page1.md /docs/somestuff2/introduction/page2.md

Both will be called introduction.htm in the root

[FransBouma]

in which root folder ? As somestuff1 and somestuff2 are different. :) (it can very well be this is clashing, not denying that as I don't know :) , I have to try it out, so I'm looking for a specific example so I can see what's happening)

[GeertvanHorrik]

Let me try to create a repro.

[GeertvanHorrik]

See https://github.com/GeertvanHorrik/DocNet_NameClashRepro

As you can see in the example, the subkey introduction is not unique (we an use introduction in several subsections). However, it will auto generate introduction.htm in the root, no matter the tree.

This causes a conflict and the user will only be able to navigate to the "last generated" introduction section.

A simple solution for this would be to include the relative navigation path in the filename of auto-generated index files.

[FransBouma]

Thanks! will look into it tomorrow! :)

[FransBouma]

Hmm, that's indeed not good. Will think about why this is, and what the best fix for this is.

[FransBouma]

I indeed think the relative nativagation path (joined together without the / separator) can be used as part of the filename. Placing it in the folder it is for might clash with files there too so that's not a solid solution.

[FransBouma]

If you have time, you can supply a fix, otherwise I'll look into it, whatever you want :)

[GeertvanHorrik]

I can provide a fix if you want, then I an finalize my docs adventure and do something fun again ;-)

[GeertvanHorrik]

Now generating this (still in the root):

Which looks much better imho.

Will create PR once you merged the other one since this also affects the NavigationLevel class.

[FransBouma]

Be careful with very long names though, windows has a limit and very long names might cause problems, if the total path gets too long. But as they're in the root I think there's not that much of a problem, they're not generated into a deep path, so I think for now this will work, we can always patch things up if there's ever a problem with this.

Yeah doc work starts as fun but degrades to misery over time, often in a timespan of a minute or two ;) :P

[FransBouma]

Fixed