SDWebImage Documentation https://sdwebimage.github.io
This repository hosts the in source documentation for SDWebImage and its related projects. You can view this at sdwebimage.github.io.
The documentation is auto-generated using DocC.
See more:
The Swift-DocC need Swift 5.5+, which is bundled in Xcode 13.0.
However, if you need generate Objective-C API documentation, need Swift 5.7+, which is bundled in Xcode 14.0
To build Static Hosting Documentation, which is the new feature talked in SwiftForum
you need to pass --transform-for-static-hosting
to docc command. However it's not available in Xcode's handy build settings, so you need:
Change the framework Xcode Project's build settings like this (use XCConfig syntax). For example, modify Module-Shared.xcconfig
in SDWebImage.
RUN_DOCUMENTATION_COMPILER = YES
DOCC_EXTRACT_SWIFT_INFO_FOR_OBJC_SYMBOLS = YES
OTHER_DOCC_FLAGS = --transform-for-static-hosting
run with Xcodebuild:
xcodebuild build -sdk iphoneos -scheme SDWebImage -configuration Release -destination generic/platform=iOS
After building, you will found something like SDWebImage.doccarchive
in the build log (actually, the BUILD_DIR
under Xcode DerivedData path)
Copy the following folder to this repo:
cp -R SDWebImage.doccarchive/documentation/sdwebimage GitHub/sdwebimage.github.io/documentation/sdwebimage
cp -R SDWebImage.doccarchive/data/documentation/sdwebimage GitHub/sdwebimage.github.io/data/documentation/sdwebimage
cp -R SDWebImage.doccarchive/data/documentation/sdwebimage.json GitHub/sdwebimage.github.io/data/documentation/sdwebimage.json
cp -R SDWebImage.doccarchive/index/index.json GitHub/sdwebimage.github.io/index/sdwebimage/index.json
Launch the simple HTTP Server locally and see on Chrome/Safari browser.
python3 -m http.server
Then use browser to open localhost:8000
- SwiftDocC does not support multiple documentations hosting on the same site.
I modify the original generated js files, and let that index.json
support the framework namespace structure. See patches/
.
See related feature request here: Support DocC references to symbols defined in another module
- SwiftDocC does not support cross-module reference symbol, unlike Apple's own documentation, like reference
Foundation.Data
symbol fromUIKit.UIImage
I check the generated js files, though we can merge the final index.json
in to the large one. However, the data/${module}.json
contains only the symbol USR for current module, when DocC generate for current module, it does not keep the outer symbol USR, so it can not reference from each other.
Anyway, jazzy does not support this feature as well. Hoping for future support.
The documentation is auto-generated using Jazzy.
[sudo] gem install jazzy
This documentation page now hosting both Core repo and other related framework's documentation. To modify the contents, just using the Markdown format and using jazzy to generate the HTML representation. Or directly modify the index.html
.
- Clone both SDWebImage, jazzy-theme and this repo
- Place them in the same folder
- Go the SDWebImage folder
- Run the following command, remember to change the version string:
jazzy \
--objc \
--author SDWebImage \
--github_url https://github.com/SDWebImage/SDWebImage \
--github-file-prefix https://github.com/SDWebImage/SDWebImage/tree/5.9.0 \
--module-version 5.9.0 \
--umbrella-header WebImage/SDWebImage.h \
--documentation=Docs/\*.md \
--undocumented-text "" \
--module SDWebImage \
--framework-root . \
--sdk iphonesimulator \
--output ../sdwebimage.github.io/SDWebImage \
--theme ../jazzy-theme/themes/apple
SDWebImage now contains many related project, like the Coder Plugins repo, the SwiftUI repo SDWebImageSwiftUI.
You should place the generated documentation output folder, inside the sub-directory of this repo.
For Swift project, take SDWebImageSwiftUI for example:
jazzy \
--author SDWebImageSwiftUI \
--github_url https://github.com/SDWebImage/SDWebImageSwiftUI \
--github-file-prefix https://github.com/SDWebImage/SDWebImageSwiftUI/tree/1.5.0 \
--module-version 1.5.0 \
--undocumented-text "" \
--module SDWebImageSwiftUI \
--framework-root . \
--sdk iphonesimulator \
--output ../sdwebimage.github.io/SDWebImageSwiftUI \
--theme ../jazzy-theme/themes/apple
For Objective-C project, it's a little trick that you have to fake an umbrella header, make the include header search path, the same as folder structure. Take SDWebImagePhotosPlugin for example:
Move the SDWebImagePhotosPlugin/Module/SDWebImagePhotosPlugin.h
-> SDWebImagePhotosPlugin/SDWebImagePhotosPlugin.h
. Then modify all the include form, from this:
#import <SDWebImagePhotosPlugin/NSURL+SDWebImagePhotosPlugin.h>
to this:
#import "Classes/NSURL+SDWebImagePhotosPlugin.h"
// And, if there are no `#import <UIKit/UIKit.h>`, add this as well
Finally, use jazzy to generate the documentation:
jazzy \
--objc \
--author SDWebImagePhotosPlugin \
--github_url https://github.com/SDWebImage/SDWebImagePhotosPlugin \
--github-file-prefix https://github.com/SDWebImage/SDWebImagePhotosPlugin/tree/0.4.0 \
--module-version 0.4.0 \
--umbrella-header SDWebImagePhotosPlugin/SDWebImagePhotosPlugin.h \
--undocumented-text "" \
--module SDWebImagePhotosPlugin \
--framework-root . \
--sdk iphonesimulator \
--output ../sdwebimage.github.io/SDWebImagePhotosPlugin \
--theme ../jazzy-theme/themes/apple