[clang-doc][GSOC] improve clang-doc html output

[PeterChou1]

This issue will serve as the overview for the final stretch of the gsoc project improve clang-doc, the first part of gsoc focused on improving the runtime speed for clang-doc, now that's completed, we can focus on improving the output of clang-docs html output

Mentors: @ilovepi, @petrhosek

These are the following issues with clang-docs current output taken from my proposal that I believe can be finished

Goal 1:
Status: WIP

Add distinction between private\protected\public\static methods which are grouped into its own section.
clang-doc makes no such distinction with its html/markdown output; all methods are filed under the ‘method’ section.

Goal 2:
Status: WIP

Add cross reference links in Clang-Docs HTML output

Goal 3:
Status: WIP

• [clang-doc] add support for block commands in clang-doc html output #101108
• [clang-doc] add support for enums comments in html generation #101282
• [clang-doc] add support for comments for members in HTML output #101255

Add support in HTML output for

• Template parameters
• Inherited Members/Methods
• Block Comments
• Enum Comments

Goal 4:
Status: WIP

Improve clang-doc CSS, ideally the output could look like the redesigned LLVM website

[ilovepi]

@PeterChou1 can you update this and probably close it out after the update, since GSOC is now complete.

[ilovepi]

@PeterChou1 are there Items left unfinished here? I think pretty much everything is done, right?

[ilovepi]

@PeterChou1 I know you have the mustache template patch ... how much does that improve the performance of the generated HTML? Over the weekend I profiled the sites generated by clang-doc for https://docs.fuchsia.dev/cpp and found that (once I fixed the links) that pages were very slow to load due to over 100,000 DOM nodes being created for the left nav bar. My understanding is that the new template should improve than, but I'm not sure based on the templates if we will sufficiently limit the scope for large code bases like Fuchsia or LLVM.

There's also some other simple optimizations we could make to index.js, like calculating the Base URL/path much earlier and avoiding so many string operations, but I think most of those will go away in the new template, so I'm not all that worried.

What are your thoughts?

[PeterChou1]

The original html loads the class/namespace/functions for the entire project on the sidebar. Meaning the every thing clang-doc found is loaded simultaneously regardless of how deeply nested it is. The mustache patch limits that to only the scope of the current class/namespace that should significantly lower the scope.

[ilovepi]

The original html loads the class/namespace/functions for the entire project on the sidebar. Meaning the every thing clang-doc found is loaded simultaneously regardless of how deeply nested it is. The mustache patch limits that to only the scope of the current class/namespace that should significantly lower the scope.

Hmm, the global namespace often has quite a lot of things. I'm still wondering if it will be an issue. For Fuchsia I think something like 30% of the entries were in the global namespace. I think we'll need to consider how to handle that once the mustache templating lands.

How soon can you have that patch ready for review? I'd really like for us to start being able to improve the HTML generation, which is hard until that lands. I'm actually hoping to start focusing a bit more on this next week, so if we can land it before Friday that would be great. If you won't have time before then, I can probably take over and get it landed.

[PeterChou1]

@ilovepi

I can have the patch ready before Friday. The current patch is quite massive for reference the current patch is here: #133161. I'd probably have to seperate it into 3 separate PR so that its easier to review.