Skip to content

Commit 9e5414e

Browse files
ayushshrivastvayushshrivastv
committed
Fix path issues in generated documentation to prevent 404 errors
1 parent 79e6b24 commit 9e5414e

File tree

5 files changed

+43
-46
lines changed

5 files changed

+43
-46
lines changed

‎.github/workflows/pages.yml‎

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -33,22 +33,8 @@ jobs:
3333
run: |
3434
swift build
3535
chmod +x ./scripts/build-docs.sh
36+
# The build script now handles path fixing automatically
3637
./scripts/build-docs.sh
37-
38-
# Create a root index.html to redirect to the docs
39-
cat > docs/index.html << 'EOF'
40-
<!DOCTYPE html>
41-
<html>
42-
<head>
43-
<meta charset="UTF-8">
44-
<meta http-equiv="refresh" content="0; url=documentation/registryapi/">
45-
<title>Redirecting to API Documentation</title>
46-
</head>
47-
<body>
48-
<p>If you are not redirected automatically, <a href="documentation/registryapi/">click here</a>.</p>
49-
</body>
50-
</html>
51-
EOF
5238
5339
- name: Setup Pages
5440
uses: actions/configure-pages@v5

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ OpenAPI is the industry standard for documenting HTTP services, but Swift develo
1313
The project is organized into several modules:
1414

1515
- `Sources/Core` - Core functionality and data models
16-
- `Sources/CLI` - Command-line interface
16+
- `Sources/CLI` - Command-line interface
1717
- `Sources/OpenAPItoSymbolGraph` - Main implementation with submodules:
1818
- `Mapping` - Mappers between OpenAPI and SymbolGraph
1919
- `Utils/DocC` - DocC integration utilities
@@ -71,7 +71,7 @@ swift run openapi-to-symbolgraph Examples/petstore.yaml --output-path petstore.s
7171
Or manually with DocC:
7272

7373
```bash
74-
xcrun docc convert YourAPI.docc --fallback-display-name YourAPI --fallback-bundle-identifier com.example.YourAPI --fallback-bundle-version 1.0.0 --additional-symbol-graph-dir ./ --output-path ./docs --hosting-base-path OpenAPI-Integration-with-DocC
74+
xcrun docc convert YourAPI.docc --fallback-display-name YourAPI --fallback-bundle-identifier com.example.YourAPI --fallback-bundle-version 1.0.0 --additional-symbol-graph-dir ./ --output-path ./docs
7575
```
7676

7777
## Viewing the Documentation
@@ -94,7 +94,7 @@ You can serve the documentation locally using one of these methods:
9494
./scripts/local-preview.sh
9595
```
9696

97-
This script creates the necessary directory structure for local testing and handles the redirects properly. This is the most reliable way to preview the documentation exactly as it will appear on GitHub Pages.
97+
This script serves the documentation directory and opens it in your browser. You will be automatically redirected to the API documentation.
9898

9999
#### Using the server script:
100100

‎scripts/build-docs.sh‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,29 @@ xcrun docc convert RegistryAPI.docc \
1515
--fallback-bundle-identifier com.example.RegistryAPI \
1616
--fallback-bundle-version 1.0.0 \
1717
--additional-symbol-graph-dir ./ \
18-
--output-path ./docs \
19-
--hosting-base-path OpenAPI-Integration-with-DocC
18+
--output-path ./docs
19+
20+
# Create a root index.html to redirect to the API docs
21+
cat > docs/index.html << 'EOF'
22+
<!DOCTYPE html>
23+
<html>
24+
<head>
25+
<meta charset="UTF-8">
26+
<meta http-equiv="refresh" content="0; url=documentation/registryapi/">
27+
<title>Redirecting to API Documentation</title>
28+
</head>
29+
<body>
30+
<p>If you are not redirected automatically, <a href="documentation/registryapi/">click here</a>.</p>
31+
</body>
32+
</html>
33+
EOF
34+
35+
# Fix paths in generated HTML files
36+
chmod +x scripts/fix-paths.sh
37+
./scripts/fix-paths.sh
2038

2139
# Make sure .nojekyll file exists
2240
touch docs/.nojekyll
2341

2442
echo "Documentation generated successfully in ./docs directory"
25-
echo "You can preview it using: ./scripts/serve-docs.sh"
43+
echo "You can preview it using: ./scripts/local-preview.sh"

‎scripts/fix-paths.sh‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/bash
2+
# Script to fix absolute paths in generated DocC HTML files
3+
4+
echo "Fixing absolute paths in HTML files..."
5+
6+
# Find all HTML files
7+
find docs -name "*.html" | while read file; do
8+
echo "Processing $file"
9+
# Replace absolute paths with relative ones
10+
sed -i '' 's|href="/|href="../../../|g' "$file"
11+
sed -i '' 's|src="/|src="../../../|g' "$file"
12+
sed -i '' 's|baseUrl = "/"|baseUrl = "../../../"|g' "$file"
13+
done
14+
15+
echo "Path fixing completed. Documentation should now work with both local serving and GitHub Pages."

‎scripts/local-preview.sh‎

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -24,30 +24,8 @@ if [ $PORT -gt $MAX_PORT ]; then
2424
exit 1
2525
fi
2626

27-
# Create the local testing directory structure
28-
echo "Setting up local testing environment..."
29-
mkdir -p docs-local/OpenAPI-Integration-with-DocC
30-
cp -r docs/* docs-local/OpenAPI-Integration-with-DocC/
31-
32-
# Create redirect index.html if it doesn't exist
33-
if [ ! -f docs-local/index.html ]; then
34-
cat > docs-local/index.html << 'EOF'
35-
<!DOCTYPE html>
36-
<html>
37-
<head>
38-
<meta charset="UTF-8">
39-
<meta http-equiv="refresh" content="0; url=OpenAPI-Integration-with-DocC/">
40-
<title>Redirecting to API Documentation</title>
41-
</head>
42-
<body>
43-
<p>If you are not redirected automatically, <a href="OpenAPI-Integration-with-DocC/">click here</a>.</p>
44-
</body>
45-
</html>
46-
EOF
47-
echo "Created redirect index.html in docs-local/"
48-
fi
49-
50-
# Start the server
27+
# Start the server directly from the docs directory
5128
echo "Starting local preview server on port $PORT..."
5229
echo "Open your browser to http://localhost:$PORT/"
53-
python3 -m http.server $PORT --directory docs-local
30+
echo "You should be automatically redirected to the API documentation."
31+
python3 -m http.server $PORT --directory docs

0 commit comments

Comments
 (0)