SDWebImage documentation

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.

DocC Generation

The documentation is auto-generated using DocC.

See more:

• Meet DocC documentation in Xcode - WWDC21 - Videos
• What's new in Swift-DocC - WWDC22 - Videos

Install Xcode (16 is required for Objective-C)

The Swift-DocC merge tool need Swift 5.10+, which is bundled in Xcode 15.2.0+

Modify build setting and build each framwework

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 to pass extra options during xcodebuild

You can find a Configs/Docc.xcconfig under this repo root path:

RUN_DOCUMENTATION_COMPILER = YES
DOCC_EXTRACT_SWIFT_INFO_FOR_OBJC_SYMBOLS = YES
DOCC_ENABLE_CXX_SUPPORT = YES
DOCC_EXTRACT_EXTENSION_SYMBOLS = YES
OTHER_DOCC_FLAGS= --transform-for-static-hosting

run with Xcodebuild:

xcodebuild build -sdk iphoneos -scheme SDWebImage -configuration Release -destination generic/platform=iOS -xcconfig Docc.xcconfig

Merge the Docc Archive

After building, you will found something like SDWebImage.doccarchive in the build log (actually, the BUILD_DIR under Xcode DerivedData path)

Then, repeat until all of frameworks doccarchive built.

Merge them into single one

xcrun docc merge SDWebImage.doccarchive SDWebImageSwiftUI.doccarchive XXX.doccarchive -o Output.doccarchive

Upgrade the documentation

After the Output.doccarchive generated, copy and override all the contents of Output.doccarchive to this repo's root path

cp -R Output.doccarchive/* $current_repo_path/

Then, git reset the index.html under repo's root path (this is our home page, see below)

git reset HEAD index.html

Upgrade/Hack the home page (rarely do this)

We has some markdown written home page, but it requires to sync the CSS/JS resources from the docc tools.

If you upgrade the toolchain, or change anything for that Home.md markdown, you need to re-generate the index.html following the steps:

1. xcrun docc convert --fallback-display-name Documentation --fallback-bundle-identifier com.dailymodtion.documentation --fallback-bundle-version 1 --output-dir Home.doccarchive Home.docc
2. Preview at Home.doccarchive and using Chrome to rendering localhost://8000/documentation/home
3. Copy all the rendered HTML and override this repo root patg index.html file
4. Remove all the <script> label inside HTML (or added type="application/json" to script tag to disable its function)
5. Preview and check the home page render correctly, see blow

Preview the documentation site

Launch the simple HTTP Server locally and see on Chrome/Safari browser.

python3 -m http.server

Then use browser to open localhost:8000

Done

1. 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](https://github.com/apple/swift-docc/issues/208)

2. SwiftDocC does not support cross-module reference symbol, unlike Apple's own documentation, like reference `Foundation.Data` symbol from `UIKit.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.

---

Jazzy (Deprecated)

The documentation is auto-generated using Jazzy.

Install jazzy

[sudo] gem install jazzy

Modify the contents

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.

Generate the SDWebImage documentation

• 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

Generate SDWebImage related project documentation

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.

Swift

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

Objective-C

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