Skip to content

Commit 44099ee

Browse files
orchetectorchetect
committed
Added documentation build script
1 parent 117bb53 commit 44099ee

File tree

5 files changed

+183
-5
lines changed

5 files changed

+183
-5
lines changed

‎Docs/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# swift-timecode DocC Generation
2+
3+
## Build and Publish
4+
5+
The docs generation procedure is mostly automated, but requires a handful of manual procedures that are not yet automated in order to build and publish.
6+
7+
1. Run the `build-docc-cached-preview.sh` command from Terminal from within the repo directory
8+
9+
- If any DocC warnings are shown:
10+
11+
1. resolve the issues in the codebase
12+
2. re-run the build script and repeat resolving issues until no more warnings are present
13+
3. make a commit
14+
15+
- When finished the generated docs path will be output to the console, ie:
16+
17+
```
18+
Generated combined documentation archive at:
19+
/var/folders/pk/3smbhvrd0p701_rpq3t0c_2r0000gn/T/tmp.Oq9smpNmnD/docs-webroot/swift-timecode
20+
```
21+
22+
As well, a local webserver on port 8080 will run to preview the documentation in a local web browser at this URL:
23+
24+
http://localhost:8080/swift-timecode/documentation
25+
26+
2. Press `Ctrl+C` in the Terminal window to shut down the local webserver and return to the shell prompt
27+
28+
3. Navigate to the generated docs path using the path that was output to the console
29+
30+
```bash
31+
cd /var/folders/pk/3smbhvrd0p701_rpq3t0c_2r0000gn/T/tmp.Oq9smpNmnD/docs-webroot/swift-timecode
32+
```
33+
34+
Then to open this folder in the Finder:
35+
36+
```bash
37+
open .
38+
```
39+
40+
4. In the local repo `docs` branch:
41+
42+
- remove all files within the `docs` subfolder except `index.html`
43+
- copy all files from the generated docs `except index.html` to replace the old docs that were deleted
44+
45+
5. See the [Post-Build](#Post-Build) section below
46+
47+
6. Commit and push to remote `docs` branch - GitHub Actions will automatically publish the site to GitHub Pages
48+
49+
## Post-Build
50+
51+
The root-level `index.html` file in the local repo `docs` branch needs to edited to include a meta event to redirect to the documentation subpath.
52+
53+
```html
54+
<head>
55+
<!-- ... -->
56+
<meta http-equiv="refresh" content="0; url=documentation/">
57+
```

‎Docs/build-docc-cached-preview.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Build docc documentation
2+
3+
# This invocation provides a stable scrach (build) directory location which allows repeated runs to
4+
# execute faster. This is useful when developing and debugging documentation generation compiler warnings.
5+
#
6+
# After building, a local web server is started to preview the documentation.
7+
8+
REPO_PATH="$(git rev-parse --show-toplevel)"
9+
BUILD_PATH="$REPO_PATH/.build"
10+
./build-docc.sh -w -s "$BUILD_PATH"

‎Docs/build-docc-cached.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Build docc documentation
2+
3+
# This invocation provides a stable scrach (build) directory location which allows repeated runs to
4+
# execute faster. This is useful when developing and debugging documentation generation compiler warnings.
5+
#
6+
# After building, the built documentation folder is opened in the Finder.
7+
8+
REPO_PATH="$(git rev-parse --show-toplevel)"
9+
BUILD_PATH="$REPO_PATH/.build"
10+
./build-docc.sh -o -s "$BUILD_PATH"

‎Docs/build-docc.sh‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Build docc documentation
2+
3+
# Arguments:
4+
#
5+
# [-s <path>] Optionally supply a scratch path (a.k.a. build path).
6+
# Defaults to temporary directory, which is unique on every script execution.
7+
# To provide a stable scratch folder, supply this argument with the path to a directory
8+
# (absolute path, or relative path to the current working directory.)
9+
#
10+
# For example, to use the default ".build" folder at the repo's root:
11+
# build-docc -s .build
12+
13+
# Swift-DocC Plugin Documentation:
14+
# https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin/
15+
16+
PACKAGE_NAME="swift-timecode"
17+
18+
usageAndExit() { echo "$0 usage:" && grep "[[:space:]].)\ #" $0 | sed 's/#//' | sed -r 's/([a-z])\)/-\1/'; exit 0; }
19+
20+
while getopts "s::owh" flag; do
21+
case "${flag}" in
22+
s) # Optionally supply a scratch (build) directory path.
23+
BUILD_PATH="${OPTARG}"
24+
;;
25+
o) # Open folder in the Finder after building.
26+
OPEN_FOLDER_IN_FINDER=1
27+
;;
28+
w) # Start a local webserver to preview documentation after building.
29+
ALLOW_WEBSERVER=1
30+
;;
31+
h) # Display help.
32+
usageAndExit
33+
;;
34+
esac
35+
done
36+
37+
# Provide default(s) for arguments
38+
if [ "$OPEN_FOLDER_IN_FINDER" = "" ]; then OPEN_FOLDER_IN_FINDER=0; fi
39+
if [ "$ALLOW_WEBSERVER" = "" ]; then ALLOW_WEBSERVER=0; fi
40+
41+
# Set up base paths
42+
REPO_PATH="$(git rev-parse --show-toplevel)"
43+
TEMP_WORKING_PATH="$(mktemp -d)"
44+
DOCC_OUTPUT_WEBROOT="$TEMP_WORKING_PATH/docs-webroot"
45+
DOCC_OUTPUT_PATH="$DOCC_OUTPUT_WEBROOT/$PACKAGE_NAME"
46+
47+
echo "Package Name: $PACKAGE_NAME"
48+
echo "Repo Path: $REPO_PATH"
49+
echo "Temporary Working Path: $TEMP_WORKING_PATH"
50+
echo "DocC Output Path: $DOCC_OUTPUT_PATH"
51+
52+
# Create output folders
53+
mkdir "$DOCC_OUTPUT_WEBROOT"
54+
mkdir "$DOCC_OUTPUT_PATH"
55+
56+
cd "$REPO_PATH"
57+
58+
# Set up build paths
59+
if [ "$BUILD_PATH" = "" ]; then BUILD_PATH="$TEMP_WORKING_PATH/build"; fi
60+
echo "Scratch (Build) Path: $BUILD_PATH"
61+
PLUGIN_OUTPUTS_PATH="$BUILD_PATH/plugins/Swift-DocC/outputs"
62+
63+
# Delete old docs from build folder, if any
64+
if [ -d "$PLUGIN_OUTPUTS_PATH" ]; then
65+
echo "Removing old build products..."
66+
rm -r "$PLUGIN_OUTPUTS_PATH"
67+
fi
68+
69+
# Custom env flag that opts-in to using the plugin as a Package dependency
70+
export ENABLE_DOCC_PLUGIN=1
71+
72+
# --disable-indexing: Indexing is only relevant to IDEs like Xcode, and not relevant for hosting online
73+
echo "Compiling docs..."
74+
swift package \
75+
--scratch-path "$BUILD_PATH" \
76+
--disable-sandbox \
77+
--allow-writing-to-directory "$DOCC_OUTPUT_PATH" \
78+
generate-documentation \
79+
--target SwiftTimecode \
80+
--target SwiftTimecodeAV \
81+
--target SwiftTimecodeCore \
82+
--target SwiftTimecodeUI \
83+
--disable-indexing \
84+
--output-path "$DOCC_OUTPUT_PATH" \
85+
--transform-for-static-hosting \
86+
--enable-experimental-combined-documentation \
87+
--hosting-base-path "$PACKAGE_NAME"
88+
89+
# Reveal output folder in finder
90+
if [ $OPEN_FOLDER_IN_FINDER == 1 ]; then
91+
echo "Opening built documentation in Finder."
92+
open "$DOCC_OUTPUT_PATH"
93+
fi
94+
95+
# Start local webserver
96+
if [ $ALLOW_WEBSERVER == 1 ]; then
97+
echo Starting localhost webserver on port 8080. Press Ctrl+C to end.
98+
echo Browse: http://localhost:8080/$PACKAGE_NAME/documentation/
99+
cd "$DOCC_OUTPUT_WEBROOT"
100+
ruby -run -ehttpd . -p8080
101+
fi

‎Package.swift‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ let package = Package(
1919
dependencies: [
2020
// used only for Dev tests, not part of regular unit tests
2121
// .package(url: "https://github.com/orchetect/xctest-extensions", from: "2.0.0")
22-
] + doccPluginDependency(),
22+
],
2323
targets: [
2424
.target(
2525
name: "SwiftTimecode",
@@ -70,8 +70,8 @@ let package = Package(
7070
)
7171

7272
/// Conditionally opt-in to Swift DocC Plugin when an environment flag is present.
73-
func doccPluginDependency() -> [Package.Dependency] {
74-
ProcessInfo.processInfo.environment["ENABLE_DOCC_PLUGIN"] != nil
75-
? [.package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.4.5")]
76-
: []
73+
if ProcessInfo.processInfo.environment["ENABLE_DOCC_PLUGIN"] != nil {
74+
package.dependencies += [
75+
.package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.4.5")
76+
]
7777
}

0 commit comments

Comments
 (0)