Multiple modules #1379
Merged
Multiple modules #1379
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Feb 8, 2024
Generated by 🚫 Danger |
|
Some pathological extension-merging... |
|
Autolinking was quite an effort; at least I understand what it was doing now. The various test specs have changes which are all improvements/bug fixes --- far too much effort to reimplement the bugs:
I am confident the rework is good, the specs exercise all the paths in so many weird ways. |
johnfairh
force-pushed
the
jf-mm
branch
2 times, most recently
from
47d6968 to
f127704
Compare
Document multiple modules which are Xcode project on their own or part of a workspace Update the build configuration * rename the command line attribute to modules * use config file for module to build Xcode project build the project with configuration from config file chore: remove tomtomsdk from jazzy feat: Add extensions to proper module. renaming of config variables for multiple modules Co-Authored-By: Pedro Alcobia <[email protected]>
Nested config file objects with selected attributes for modules. Add 'doc module name' sourcedeclaration attribute saying where the declaration was found, vs. 'module name' saying where the decl's nominal is from. Quick and dirty updates to prototype code to make it pass rubocop.
Provide a separate option to set the docset title instead of using the module name. Refactor to pull all the docset stuff into the docset code.
Add a new flag to set this thing manually.
Make the page breadcrumbs actually reflect the navigation hierarchy. Include a type's module name when it's from an external module or not clear from the breadcrumb list. Affects all specs.
Each module into its own directory. Each module that has extensions in its own subdir No need to separate classes/enums etc even in ObjC
Add —merge-modules all/extensions/none and implement merging and unmerging with custom categories and guides. User docs for this later when happy. Extend test case to demonstrate.
Pure refactor.
Include a note where necessary to show what the user has to import to get access to the declaration. Three mechanisms for showing module source, increasingly fine granularity: 1. The outer group name in the left nav/first breadcrumb. This is set to the module name for merge=none/extns. 2. The top-level decl name in the breadcrumbs. This includes the module name only when mech#1 fails. 3. A decl note in the parent page. For when mech#1,2 fail. This commit. For example a decl added by an extension or a top-level decl with no children (eg. free function, marker protocol). The idea is that jazzy use the widest-scope mechanism possible, falling back to the more visually noisy ones only when necessary.
This is to resolve the issue of merging extensions that provide protocol compliance -- in this case there may be no members to annotate and show the source module. A bit messy and not entirely complete because of the way the code is structured -- really we should rework 'declaration' to be a list of stuff for the templating layer but it is already tangled up with html because of Rouge. Good enough though, covers everything, and in reality these are unusual cases.
Add module-aware doc index tree. Reimplement autolinking to use the tree. This makes linking module-aware and deals with the ambiguities.
Rebase, docs, last-minute objc fixes ObjC namespaces are confused by the 'tag' and typedef rules from ye olde C so have to revert to the fuller directory structure. To make things simpler and less risky, just keep that for the Swift version too.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Thanks to the efforts from last year (#1369) there's a prototype and a lot of thoughts about this, so let's see how much further it can go without too much risk to existing projects.
Testcase / demo in spec/integration_specs/jazzy_multi_modules, 3x Swift & 1 ObjC module.
Ready to go now, will let it sit a bit first.