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 exampel 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 use this swift-docc plugin for builds.

Issue

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.

@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.

Action plan

• Wait for improvements of the swift-docc plugin
• Check if the tool supports Mermaid charts, it is not today (Support of Mermaid charts for Markdown files swiftlang/swift-docc#1026)
• When the tool gets updated, refactor our generateDoc.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

What we expect

• Have a rendering of Mermaid charts
• Replace hard-coded hyperlinks by DocC syntax (e.g. /OUDSTokensComponent or doc://OUDSTOkensRaw)

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)

generateDoc.sh.zip

[pylapp]

Need specifications to go further.