[clang-doc] Mustache HTML doesn't have a top level index page

[evelez7]

With reverting back to a nested directory structure in the HTML Mustache backend, I noticed that it never had a top level index.html page. The top-level global namespace index.html is inside docs/html/GlobalNamespace (before we had separate documentation directories, it was inside docs/GlobalNamespace). The "legacy" HTML backend has a top-level index.html which lists all the namespaces including the global namespace. The "legacy" HTML directory looks like this:

docs/
    index.html # Mustache HTML doesn't have this
    GlobalNamespace/
        index.html

That means that it's harder to show documentation on a static site. In GitHub Pages, you will have to navigate to the GlobalNamespace URL, e.g. here, where as the actual root URL doesn't point to anything (see here). I think that's fairly counterintuitive. In a real world setting, we wouldn't be able to easily navigate to clang.com/docs, we'd have to go to clang.com/docs/GlobalNamespace. If someone wanted an index.html at the top level, they'd have to pull it up one directory which breaks links.

We can either have a new index.html page at the root html/ level which just shows namespaces or maybe can host a custom intro (like Doxygen does), or we can just output the GlobalNamespace stuff into that root directory. I think in the conversations I've had with Paul, we probably don't want to dump a bunch of info when someone loads into the first page.

Thoughts? @ilovepi @petrhosek

[ilovepi]

I think we discussed this initially when we moved to the flat directory structure.

IMO we should probably have some kind of basic navigation page. To start, that can link to the GlobalNamespace I'd guess and we can discuss more advanced navigation as we evolve.

[ilovepi]

Thinking a bit more, I guess we'd want a new template for the root index.html, and then figure out how to best customize that for a good navigation experience. Some of the logic IIRC for the backlinks in the other templates will need to be updated too, but my memory is fuzzy w/o staring at the real HTML output.