Context
Hello everyone, I'm a freshly graduate engineer currently learning Swift and Apple ecosystem frameworks as I wish to become an Apple Developer / Engineer.
I made a very simple and light Swift package but I cannot build the documentation using DocC.
Issue
See my project here on github and explanations below.
Behavior
- Building Documentation for my Swift package results in an empty page with only my Package name.
- Adding a documentation catalog with a start page work but only the start page is displayed after building. None of my structs in any sources files appears in the built documentation.
- Trying to add symbol linking to my sources files's structs in the start page (using double backquotes) results in the Topic section not built and a warning "MyStruct doesn't exist at '/MyPackage'"
What I tried
I found multiple information while looking for a solution, so I tried everything.
- None of my structs / classes have the same name as the package
- I did not remove the Topics section in the start page of the documentation catalog, neither I removed the Header 2 formatting.
- My documentation catalog and my sources files lies within MyPackage/Sources/MyPackage/
- I compared my starting page and folder architecture with the Sloth demo project
- I did comment my structs / classes / functions with three slash /// using Xcode shortcut to pre-write documentation
Technical Specifications
- macOS 14.5
- MacBook Pro M3 Pro 18Go
- Xcode Version 15.4 (15F31d)
- swift-tools-version: 5.10
Images
Conclusion
I have no idea what else to do and if I am doing something wrong. Any feedback or solution on my issue would be really appreciated as I'm doing my best to learn the best practices to become an Apple developer.
Thank you.
Hello,
The reason why none of your symbols appear in the documentation is that all your structs, classes, and functions are "internal" to the framework. This is because symbols in Swift have a "internal" access level by default.
Documentation for a framework is aimed towards consumers of that framework—who can only access the frameworks public API—so the documentation only includes framework's public symbols.
If you were documenting an app or executable, the documentation would include internal symbols as well.
If you make the LifeModel class "public", DocC will find it and the warning about it not being found for the link will go away. However, the "How to use" topic still won't be displayed in your documentation because it doesn't organize any symbols or articles.
DocC uses "topics" to organize symbols or articles into "groups" by linking to them in an unordered list. For more information, see the Arrange top-level symbols using topic groups section of DocC's documentation.
If you intended for "How to use" to organize symbols of your framework you need to add an unordered list of links in it, below the rest of the content in the topic. For example:
- ``LifeModel``
- ``LifeModel/startSimulation(at:)``
- ``LifeModel/stopSimulation()``
On the other hand, if you intended for "How to use" to be a section of general content, then you could instead move it above the ## Topics header to change it into a regular section of content in your documentation.
