Improving Jazzy Documentation for Multiple Modules #1369
Conversation
Document multiple modules which are Xcode project on their own or part of a workspace
|
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 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:
...need to eventually go through them all. |
* rename the command line attribute to modules * use config file for module to build Xcode project
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. Also the renamed the parameter from: "--multiple_modules" to: "--modules" |
|
I think there are two use cases for building multiple modules:
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
- MySchemeBThen 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 |
| def self.multiple_modules(options) | ||
| modules_parsed = Array[] | ||
| options.modules.each do |arguments| | ||
| module_parsed_string = Dir.chdir(arguments['source_directory']) do |
There was a problem hiding this comment.
Need to be a bit careful using source_directory here - see the special treatment the top-level option gets in config.rb, needs full-path expansion and using pwd if the field's not set.
| end | ||
|
|
||
| # Get from the remaining docs if there are extensions that should also be part of this module. | ||
| group = group.compact.map { |group| |
There was a problem hiding this comment.
I get what this is doing; some issues/questions:
- Using a child decl to identify the declaring module is neat, but not all extensions have children (think
extension SomeType : MyProtocol {}). - When naming
newdochow about including the originating module name? So it would beMyModule+Swift.Intor something -- otherwise not sure how the user knows where the extended type is from. (Or even justSwift.Intgiven this is already nested underMyModule) - I don't understand the scenario on line 137 where there is stuff left over that doesn't belong to any of the modules. What is an example of this?
About point 1, maybe think about changing how parse() works for multiple modules: could do each module's JSON one by one, then would always know which module is being worked on. At the moment group_docs_per_module is really just undoing work that's already been done to combine everything.
| 'in a custom category appear in generic groups at the ' \ | ||
| 'end. Example: https://git.io/v4Bcp', | ||
| config_attr :modules, | ||
| description: 'Array of modules that are going to be documented ' \ |
There was a problem hiding this comment.
This description is unclear to me. I assume it's a list of modules, since array is an implementation concept, and they are not "being documented".
The line with the arguments puzzles me too, but maybe I need to dive into the tool more first.
| raise 'Usage of config and comand line' | ||
| if modules_configured && module_name_configured | ||
| raise 'Jazzy only allows the use of a single command for generating documentation.' \ | ||
| 'Using both module configuration and modules configuration together is not supported.' |
There was a problem hiding this comment.
This could also be a warning that we'll add the single module given to the list of modules and just proceed.
|
Continued in #1379 |
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,...,ModuleNameNSupport 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,...,ModuleNameNProposal PR: #1363