[Documentation] Improve DocC documentation hierachy, navigation and charts rendering

[pylapp]

Context

Today, we choose to use DocC, the Apple solution for Swift documentation. The tool is quite recent, it allows for example to build documentation from Xcode for developers, export this documentation as archives, and also build an HTML version of all the documentation of the project.

We used this swift-docc plugin for builds before, but it failed to manage UIKit API as it seems to be more dedicated to macOS API.

However, even if the tool works well for Swift Package which has one target, things get complicated for libraries with several targets like our, even if it is quite common to have several targets in fact. We tried also others tools like xcode build suite, bit it faield with configuration of packages and targets.

@ludovic35 spent a lot of time to set up DocC and to think about a software solution which will gather all documentation of all modules and create a global HTML page as index refering to all other indexes. But the navigation between the HTML pages of several targets, here between our modules, is broken. The Apple tool (in its version 1.4.2 today) failed to make links and navigation between pages of several modules. That is the reason why in some parts of our documentation we refer to HTML pages so as to keep hyperlinks and references navigable.

Issue

We have hard coded hyperlinks refering targets eachothers. We extract assets and merge JSON from our doccarchives, that is tinkering and not clean at all.

The Mermaid charts are not rendered as they are rendered in the GitHub viewers.

Action plan

• Wait for improvements of the swift-docc plugin
• Check if the tool supports Mermaid charts, it is not today (https://github.com/swiftlang/swift-docc/issues/1026)
• When the tool gets updated, refactor our uploadWebDoc.sh script so as to use the suitable feature in the best way and get a global index.html file with all navigable links
• Maybe integrate Boosted to have a lovely page
• Maybe use Netlify for documentation preview, if useful
• Stop picking and merging assets

What we expect

• Have a rendering of Mermaid charts
• Replace hard-coded hyperlinks by DocC syntax (e.g. /OUDSTokensComponent or doc://OUDSTOkensRaw)
• No more assets picking and JSON merging for the final HTML site

Resources

• Writing Symbol Documentation in Your Source Files (swift.org)
• Host and Automate your DocC documentation (medium.com)
• How to link to documentation from another module/package in xcode docc? (stackoverflow.com)
• Generating API Documentation for Multiple Targets with DocC (pspdfkit/com) (TODO: try again to reproduce)
• Combined documentation of multiple targets (forum.swift.com
• Use cases for combined documentation of multiple targets in Swift-DocC (forum.swift.com)
• Building multi-platform documentation with DocC (danielsaidi.com)
• Allow combined documentation of multiple targets (github.com)

[pylapp]

Need specifications to go further. blocking because no specifications, on hold because not mandatory no prioritary