Create DocC based documentation site

[stevenzeck]

This PR creates a DocC based documentation site for the Swift toolkit. You can see what the website looks like. I'll keep it up until this is merged (if merged) and built.

Changes

1. Added a shell script file to generate the documentation and site. You can run this locally and it's used in the GitHub Actions workflow.
2. Two supporting files for the homepage and navigation (NavigatorOverview.md and Readium.md).
3. An actual GitHub workflow file. I left it as on workflow_dispatch, though you might have to add on push to a branch for it to show up properly on the Actions page.
4. Added a couple items to .gitignore for testing locally.
5. Added the swift-docc plugin package.
6. Fixed existing documentation comments in the code. I separated this into two different commits:

a. The first one removes the double tick links that try and go outside the module or the entire library. It otherwise warns in the documentation generation output.
b. The second fixes parameters that either were not documented, or were documented and don't exist in the function anymore.

@mickael-menu if you have time when reviewing, please look over b. above to ensure the parameter comments look correct to you.

[mickael-menu]

Thanks Steven! I reviewed the doc comments update, it's all good 👍

[stevenzeck]

@mickael-menu Ready for another review.

[Copilot]

Pull request overview

This PR introduces a DocC-based documentation site generation pipeline for the Swift toolkit, including a local generation script and a GitHub Actions workflow, plus a set of documentation comment fixes intended to reduce DocC warnings and improve generated reference docs.

Changes:

• Add DocC site content entrypoints (docs/Readium.md, docs/NavigatorOverview.md) and generation script (generate-docs.sh).
• Add a GitHub Actions workflow to build and deploy the generated site to gh-pages.
• Update many Swift doc comments to use DocC-friendly parameter documentation and link formatting.

Reviewed changes

Copilot reviewed 32 out of 33 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/Readium.md	Adds DocC TechnologyRoot landing page and topic links.
docs/NavigatorOverview.md	Adds an article-style overview page and topic links for Navigator docs.
Sources/Streamer/PublicationOpener.swift	Doc comment link formatting adjustments for DocC.
Sources/Streamer/Parser/Readium/ReadiumWebPubParser.swift	Expands initializer parameter documentation to cover all parameters.
Sources/Streamer/Parser/PublicationParser.swift	Doc comment link formatting adjustments for DocC.
Sources/Shared/Toolkit/XML/XML.swift	Improves parameter/throws documentation for XML document factory API.
Sources/Shared/Toolkit/URL/URLProtocol.swift	Doc comment link formatting adjustments for DocC.
Sources/Shared/Toolkit/URL/RelativeURL.swift	Doc comment link formatting adjustments for DocC.
Sources/Shared/Toolkit/URL/AnyURL.swift	Doc comment link formatting adjustments for DocC.
Sources/Shared/Toolkit/HTTP/DefaultHTTPClient.swift	Adds missing parameter docs for initializers (delegate/configuration).
Sources/Shared/Toolkit/Format/Sniffers/DefaultFormatSniffer.swift	Expands initializer documentation to include xmlDocumentFactory.
Sources/Shared/Toolkit/Data/Resource/BufferingResource.swift	Expands initializer parameter documentation.
Sources/Shared/Publication/Services/Content/ContentTokenizer.swift	Expands factory function parameter documentation.
Sources/Shared/Publication/Accessibility/AccessibilityMetadataDisplayGuide.swift	Doc comment link formatting adjustment for DocC.
Sources/Shared/Logger/Logger.swift	Expands log enabling function docs to cover all parameters.
Sources/OPDS/OPDSParser.swift	Updates parse docs to match signature and completion usage.
Sources/OPDS/OPDS2Parser.swift	Improves parse docs (parameters/returns/throws) for v2 parsing.
Sources/OPDS/OPDS1Parser.swift	Improves parse docs (parameters/returns/throws) for v1 parsing.
Sources/Navigator/VisualNavigator.swift	Updates parameter docs for goLeft/goRight navigation APIs.
Sources/Navigator/Input/InputObservableViewController.swift	Doc comment link formatting adjustment for DocC.
Sources/Navigator/Input/InputObservable.swift	Doc comment link formatting adjustments for DocC.
Sources/Navigator/EPUB/CSS/HTMLFontFamilyDeclaration.swift	Expands method parameter docs for clarity.
Sources/Navigator/Decorator/DecorableNavigator.swift	Expands method parameter docs to include group.
Sources/LCP/LCPService.swift	Expands initializer and method parameter docs; DocC link formatting updates.
Sources/LCP/LCPLicense.swift	Expands renewal method parameter docs.
Sources/LCP/Authentications/LCPAuthenticating.swift	Removes outdated completion parameter docs after async API shape.
Sources/Internal/JSON.swift	Expands parse helper docs to include json parameter.
Sources/Adapters/LCPSQLite/SQLiteLCPLicenseRepository.swift	Doc comment link formatting adjustment for DocC.
Sources/Adapters/GCDWebServer/GCDHTTPServer.swift	Expands initializer docs to include assetRetriever.
Package.swift	Adds swift-docc-plugin package dependency.
BuildTools/Scripts/generate-docs.sh	Adds a local DocC site generation script (build symbol graphs, filter, convert, output site).
.gitignore	Ignores local DocC build artifacts and generated site output.
.github/workflows/docs.yml	Adds workflow to generate and deploy documentation to GitHub Pages (gh-pages).

Comments suppressed due to low confidence (1)

Sources/Shared/Toolkit/URL/URLProtocol.swift:16

• Typo/consistency: “foundation URL” should be “Foundation URL” (capitalized) to match the previous sentence and the framework name.

    /// Returns a foundation `URL` for this URL representation.
    var url: URL { get }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mickael-menu]

Thank you @stevenzeck!