Hi there! I encounter a trouble where swift docc plugin can't generate documentation folder and generates only tutorials folder. If I use Xcode to generate documentation, that doccarchive will have data/documentation and data/tutorials folders.
I've no idea why swift docc plugin has this critical bug.
I try to build documentation in this project: GitHub - AdaEngine/AdaEngine: Multi-platform 2D and 3D game engine written on Swift
Hi @SpectralDragon ,
This isn't an issue with Swift DocC so much as what's in the project.
I checked out the project at it's current head and ran the command:
swift package --disable-sandbox preview-documentation --target AdaEngine
Just to see what's happening. There's a lot of warnings in the content as that spins up about unreferenced information. The most relevant is:
Article-only documentation needs a TechnologyRoot page (indicated by a `TechnologyRoot` directive within a `Metadata` directive) to define the root of the documentation hierarchy.
The content of the docc catalog appears to reference no symbols from the code, and has only an article within it, and there's no root page that matches the module name for it to get a handle on. DocC is doing it's best to render the content that IS there, but it doesn't have enough information to set up the articles, only the tutorials.
I believe there should be a single markdown file in that catalog that starts with something akin to:
# ``AdaEngine``
...
Alternately, and what the warning was about, is you can include a markdown file with the @TechnologyRoot directive in it, if you're trying to create a standalone set of articles without any code reference documentation included.
I'm not sure what the goal of the documentation is in this case, but the reason you're not seeing the articles is because of the content there, not DocC. Hopefully this gives you some starting points for how to resolve your project's documentation to what you want.
Thanks for your answer!
Articles is a great part of future documentation, but now for my case I need doc references like vapor does: Documentation
I'd recommend starting by creating a top level page along the lines of what's covered in Adding Structure to your Documentation Pages. The simplest starting point would be to create a new file in the catalog directory, maybe named "Documentation.md" (the name of the file is irrelevant, the relevant detail is what is IN the file), and start out with the bit:
# ``AdaEngine``
...a one-line abstract about your engine...
## Overview
...this is where you can put the multiple paragraphs of summary about the project....
## Topics
### HeadingAboutContent
- ``OneOfYourSymbols``
- ``AnotherOneOfYourSymbols``
That's the loose format - the very first line is the critical bit - the bits between the double back-ticks should be the same as a package name, at which point DocC knows that this is the top-level page for the module. The rest is the DocC convention standard for how it's expecting documentation to be laid out.