Improving Jazzy Documentation for Multiple Modules

[argjiramala-tomtom]

This pull request introduces enhancements to the Jazzy documentation tool, specifically focusing on supporting multiple modules within Xcode projects or workspaces.

To summarize the changes made:

• New Command Line Attribute: A new command line attribute called "modules" has been added. This attribute allows users to specify multiple module names when generating documentation using Jazzy. Usage example: jazzy --modules ModuleName1,ModuleName2,...,ModuleNameN

• Support for Workspace-based projects: If you have multiple Xcode projects that can only be successfully built using a workspace, follow these steps:

a. Each module should have its own configuration file with "xcodebuild_arguments" specified

Usage example: jazzy --modules ModuleName1,ModuleName2,...,ModuleNameN

Proposal PR: https://github.com/realm/jazzy/pull/1363

[johnfairh]

Thanks for the PR -- raises some interesting issues about CLI/config for multiple modules.

I don't understand the workspace problem you are trying to solve: the way it's described and coded seems very specific to your personal project/environment. Can you explain the problem you have?

On the design side:

We should have just one parameter --modules that can take a list of modules, with the default single-module mode falling out as a subset of that.

I think what the piece about workspace/scheme stuff reveals is that some CLI/config parameters need to be per-module scope rather than global. I can't think how to do that on the CLI so might have to be config-file only. So those per-module flags might include:

• --build-tool-arguments (which would allow your scheme/workspace stuff I guess)
• --source-directory (maybe - your example seems to need this but needs investigation!)
• --swift-build-tool (probably not -- I think it's OK to say that if you're building multiple modules then they share this)
• --sourcekitten-sourcefile (eg. mixed objc+swift modules)

...need to eventually go through them all.

[argjiramala-tomtom]

Thanks for the PR -- raises some interesting issues about CLI/config for multiple modules.

I don't understand the workspace problem you are trying to solve: the way it's described and coded seems very specific to your personal project/environment. Can you explain the problem you have?

On the design side:

We should have just one parameter --modules that can take a list of modules, with the default single-module mode falling out as a subset of that.

I think what the piece about workspace/scheme stuff reveals is that some CLI/config parameters need to be per-module scope rather than global. I can't think how to do that on the CLI so might have to be config-file only. So those per-module flags might include:

• --build-tool-arguments (which would allow your scheme/workspace stuff I guess)
• --source-directory (maybe - your example seems to need this but needs investigation!)
• --swift-build-tool (probably not -- I think it's OK to say that if you're building multiple modules, then they share this)
• --sourcekitten-sourcefile (eg. mixed objc+swift modules)

...need to eventually go through them all.

The problem with the workspace was when the project could be built only through the workspace by specifying the scheme. The issue was solved by using the jazzy config file of the module. I have modified that part, where now when building the project it uses the module config file instead of the global config-file.

Also the renamed the parameter from: "--multiple_modules" to: "--modules"

[johnfairh]

I think there are two use cases for building multiple modules:

1. All Jazzy needs is the module name, SPM/Xcodebuild will just work. This will be very common especially for SPM and the 'App + Extensions in one Xcode project' that users often ask about. This can work on the command line or in the config file. This could be a new --modules basically just like in the PR today.
2. Jazzy needs special build flags for each module. This is needed for Xcode with workspaces and schemes and anything with more complicated build flags (and any Objective-C module in the future). I think this has to be config-file only, something like this where custom_modules is an array of objects whose keys are about the module:

custom_modules:
 - name: ModuleA
   build_tool_arguments: [ '-workspace', 'MyWorkspace', '-scheme', 'MySchemeA']
   source_directory: # for example, if this is necessary
   # any other per-module configuration
 - name: ModuleB
   build_tool_arguments:
    - -workspace
    - MyWorkSpace
    - -scheme
    - MySchemeB

Then there's some config code to write to look at these sources of modules, raise an error if the user has given multiple, and turn them into some single format for the rest of the code.

(I wrote custom_modules as an example name here because I don't have any good ideas and it goes with custom_categories which is the other major config-file only thing...)

[johnfairh]

Continued in #1379