Custom modules categories based on json files

[argjiramala-tomtom]

👋 Hey jazzy community!

I wanted to share a feature proposal for enhancing the Jazzy experience for our TomTomSDK API reference. Currently, Jazzy is used to build the API references for our navigation app, but it doesn't fully meet our needs. Here's what we have and what we need:

📚 What we currently have for API Reference documentation: We have a custom index.html page that combines all the modules into a single list. You can check it out here: link to current documentation

📝 What we need: We want to provide a better user experience when navigating between APIs from different modules. We would like to have seamless navigation, similar to what Jazzy already offers within a single module.

💡 Concept:

🤔 Questions:

• Does it make sense to have this as a Jazzy feature?
• If it makes sense, how would you suggest implementing it from an architectural perspective of the current library?

📋 What does this PR (Pull Request) contain? Here's a breakdown of the changes we made:
* precondition (Generate .json files using SourceKitten, following the instructions in the Jazzy repository)*

• We used the .json file names to create custom categories per file.
• We modified the 'group_docs' (labeled as 'group_docs2' in the PR) by adding an extra parameter for dynamicCategories.
• We modified the 'group_type_categories' (labeled as 'group_type_categories2' in the PR) by creating a new group based on the module name.

* Please note that this implementation is still a work in progress and may not cover all cases, but it illustrates what we aim to achieve.*

We appreciate your feedback and suggestions on how to improve this feature proposal.

[johnfairh]

Yes it's a valid feature to create documentation for multiple modules at once, so you could write jazzy --modules ModuleA,ModuleB and get a complete docs site.

Issue #564 is the tracker for this.

The general top-level issues that I remember are:

1. File layout on disk for multi-module cases with back-compatibility for single-module
2. Autolinking between/within modules (ie. with/without module name)
3. UI - extensions of types provided by other modules
4. UI - organise/design the left nav and page breadcrumbs. Probably two sensible defaults (merge modules like today, split modules out as in your prototype). Deal with custom categories/abstracts
5. (edit:) Config options design - what is per-module, what is global (see Improving Jazzy Documentation for Multiple Modules #1369)

If all you want from jazzy is the output of your prototype then I think you should just use custom_categories to organise the combined sourcekitten JSON site -- you could write a script to generate that from the JSON if you didn't want to maintain it.

It is disappointing that DocC hasn't addressed this use case yet but Apple did talk about working on it fairly recently - there's a good chance it will appear in the next couple of years.

[johnfairh]

Continued in #1379