Added warning for multiple root pages

[ayushshrivastv]

Summary

Added Warning for Multiple Root Pages Issue #1170

This pull request introduces warnings to alert developers when their documentation contains multiple root pages, resolving issue #1170. These warnings aim to highlight common configuration errors when using the docc convert tool directly, improving the debugging experience for documentation authors.

The implementation addresses three specific scenarios:

1. Multiple Symbol Graph Modules as Root Pages
   Triggered when documentation includes more than one symbol graph module (e.g., multiple .symbols.json files).

2. Mixed Root Types
   Occurs when documentation combines symbol graph modules with manually defined technology roots.

3. Multiple Manual Technology Roots
   Detected when documentation contains multiple pages marked with the @TechnologyRoot directive.

How to Try It Out

Example: Multiple Symbol Graph Modules

To test the warning for multiple symbol graph modules, create a documentation catalog structured as follows:

file.docc/
  ├── Module1.symbols.json
  ├── Module2.symbols.json
  └── Info.plist

Run the command:

docc convert file.docc

Expected output:

warning: Documentation has multiple symbol graph modules as root pages
Found multiple root pages from symbol graph files: 'Module1', 'Module2'. The primary root page can't be determined.

warning: Documentation has both symbol graph modules and manual technology roots
Found symbol graph modules ('MyModule') and manual technology roots ('GettingStarted'). The symbol graph modules are considered primary roots, making any manual @TechnologyRoot pages unexpected extra roots.

warning: Documentation has multiple manual technology roots
Found multiple pages with @TechnologyRoot directive: 'APIReference', 'GettingStarted'. The primary root page can't be determined.

Similar steps can be followed to test mixed root types or multiple manual technology roots by adjusting the catalog contents accordingly.

Benefits

• Immediate Feedback: Warns developers about structural issues in their documentation as they occur.
• Clearer Debugging: Helps explain why documentation may not render or behave as intended.
• Enhanced Usability: Especially useful for developers using docc convert directly, outside of integrations that might pre-validate inputs.

These warnings streamline the process of identifying and fixing configuration problems, making documentation authoring more intuitive.

Checklist

• [✅] Added tests to verify warning behavior across all scenarios.
• [✅] Ran the ./bin/test script and confirmed it succeeded.

[d-ronnqvist]

This is your 4th PR for the same issue and you haven't addressed the feedback from the 3rd PR. If you open a 5th PR I will immediately close it without reviewing.

When you need to make changes to a PR, do so by updating/editing the existing PR. Don't open a new one for each change. If you don't know how to update a PR, ask for help or do a web search for "github update pull request" and see if some of the search results tell you how.

[ayushshrivastv]

I’ve been testing the code locally and it seems to be working fine. I have tested it with different scenarios and by creating multiple symbol graphs or by multiple pages, the code is working properly with the test cases. The warning message is showing up, but I can’t figure out why it’s not formatted correctly. I tried switching to a different branch and unchecking all the formatting settings, but the problem still persists. When I push the code again, I get the same error.

I’m familiar with pushing changes to the same pull request, but when I look at the changes in the source control panel of Cursor, I only see the edited part of the code, with the line reformatted not visible there. I can only see changes I did, either addition or removal of code, which I did during the process.

To address this issue, I attempted to resolve it by pushing the code with various branches, anticipating that this would resolve the problem. However, this approach did not yield any positive outcomes. Subsequently, I am trying to identify the root cause of the issue by exploring the Swift forums. I realize my mistake, and I sincerely apologize!

The ./bin/test script runs perfectly without any errors related to my changes. However, it exited with code 1 due to a license header check failure. Specifically, it couldn’t find the required headers in the file ‘./bin/make-test-bundle/.build/arm64-apple-macosx/debug/make_test_bundle.build/DerivedSources/resource_bundle_accessor.swift’.

[franklinsch]

Hi @ayushshrivastv, thank you for your interest in contributing! As David pointed out above, it's preferred to keep the same PR to iterate on changes so that we can keep the feedback centralized. It seems like there is still feedback to address from the previous PRs, so let us know when your work is ready for review.

For the formatting issues, you can use git checkout to restore the state of the file to a previous version. Let us know if we can provide guidance, and thank you for contributing!

[ayushshrivastv]

It may sound silly, but when I review code changes from the Cursor GitHub source control panel graph, I see added warning code which I did. However, when I look at the GitHub files, I see a significant amount of whitespace. Despite everything appearing to work properly when I stage the changes, I encounter a lot of whitespace when I push the code to GitHub. Does the repository have a Swift formatter installed, as I don’t encounter this issue when pushing my code to other repositories?

[d-ronnqvist]

This repository doesn't have a formatter. My guess is that something in your local workflow is trimming whitespace lines in the entire file, not just the lines that you changed.

You can either use git diff --cached to see the staged changes before you commit or git show to see the changes of the commit before you push.