Skip to content

Commit c37aae4

Browse files
ayushshrivastvayushshrivastv
committed
Setup GitHub Pages with DocC documentation structure and landing page
1 parent dd10765 commit c37aae4

File tree

5 files changed

+154
-8
lines changed

5 files changed

+154
-8
lines changed

‎.github/workflows/pages.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v3
14+
15+
- name: Setup Node.js
16+
uses: actions/setup-node@v3
17+
with:
18+
node-version: '16'
19+
20+
- name: Create gh-pages structure
21+
run: |
22+
# Create the directory structure for GitHub Pages
23+
mkdir -p gh-pages
24+
25+
# Copy the DocC documentation to the root of the GitHub Pages site
26+
cp -r docs/* gh-pages/
27+
28+
# Copy our landing page as the index.html
29+
cp landing-page.html gh-pages/index.html
30+
31+
# Copy other necessary files
32+
cp -r assets gh-pages/ || true
33+
touch gh-pages/.nojekyll
34+
35+
- name: Deploy to GitHub Pages
36+
uses: peaceiris/actions-gh-pages@v3
37+
with:
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
publish_dir: ./gh-pages
40+
publish_branch: gh-pages
41+
force_orphan: true

‎README.md‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This project aims to create a tool that automatically converts OpenAPI specifications into Swift-DocC compatible documentation. By bridging OpenAPI and Swift-DocC through SymbolGraph files, we'll enable seamless documentation generation for REST APIs within the Swift ecosystem.
44

5-
The project is still in its very early stage, and I’m actively working on improving it.
5+
The project is still in its very early stage, and I'm actively working on improving it.
66

77
Google Summer of Code @Swift project to integrate OpenAPI Integration with Swift-DocC: Automated API Documentation Generation.
88

@@ -13,9 +13,9 @@ Google Summer of Code @Swift project to integrate OpenAPI Integration with Swift
1313
Currently, Swift developers maintaining REST APIs need to manually document their APIs in DocC while separately maintaining OpenAPI specifications. This creates duplicate work and potential inconsistencies between API specifications and documentation.
1414

1515
## Proposed Solution
16-
Command line tool to simplify API documentation for Swift developers. It parses OpenAPI JSON/YAML files using OpenAPIKit Swift Library, transforms schemas and endpoints into DocC ready SymbolGraph files with createSymbolGraph, and outputs “symbolgraph.json.” Users then execute docc convert symbolgraph.json --output-path docs to create HTML docs, enhanced by a static “API.docc/” catalog for custom pages. For GSoC, I’ll extend support for complex schemas like nested objects and arrays, automate DocC conversion, and add live previews, ensuring effortless, consistent API documentation from OpenAPI specs.
16+
Command line tool to simplify API documentation for Swift developers. It parses OpenAPI JSON/YAML files using OpenAPIKit Swift Library, transforms schemas and endpoints into DocC ready SymbolGraph files with createSymbolGraph, and outputs "symbolgraph.json." Users then execute docc convert symbolgraph.json --output-path docs to create HTML docs, enhanced by a static "API.docc/" catalog for custom pages. For GSoC, I'll extend support for complex schemas like nested objects and arrays, automate DocC conversion, and add live previews, ensuring effortless, consistent API documentation from OpenAPI specs.
1717

18-
`swift run openapi-to-symbolgraph <path-to-openapi.json>`: Runs your tool to parse and generate “symbolgraph.json.”
18+
`swift run openapi-to-symbolgraph <path-to-openapi.json>`: Runs your tool to parse and generate "symbolgraph.json."
1919

2020

2121
`docc convert symbolgraph.json --output-path docs`: Converts the SymbolGraph into HTML documentation.
@@ -85,7 +85,7 @@ swift run openapi-to-symbolgraph api.json --output ./symbols
8585
```
8686

8787

88-
![Screenshot 2025-03-17 at 1 57 27 PM](https://github.com/user-attachments/assets/dbb60011-201a-4b72-bbdb-d9b91e11489f)
88+
![Screenshot 2025-03-17 at 1 57 27 PM](https://github.com/user-attachments/assets/dbb60011-201a-4b72-bbdb-d9b91e11489f)
8989

9090

9191
## Project Structure
@@ -104,6 +104,38 @@ swift run openapi-to-symbolgraph api.json --output ./symbols
104104
- [OpenAPIKit](https://github.com/mattpolzin/OpenAPIKit.git)
105105
- [Swift DocC SymbolKit](https://github.com/swiftlang/swift-docc-symbolkit.git)
106106

107+
## Documentation Structure
108+
109+
The project documentation is hosted on GitHub Pages at [https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/).
110+
111+
### Documentation Components
112+
113+
1. **Landing Page**: A simple entry point that introduces the project and provides links to the API documentation.
114+
115+
2. **API Documentation**: The DocC-generated documentation from the OpenAPI specification, providing:
116+
- API endpoint details
117+
- Request/response schemas
118+
- Interactive examples
119+
- Searchable interface
120+
121+
### Viewing the Documentation
122+
123+
- The main URL redirects to an informational page about the DocC documentation.
124+
- From there, you can access the full DocC-generated API documentation.
125+
- The documentation is generated from the OpenAPI specification using the command:
126+
```bash
127+
docc convert symbolgraph.json --output-path docs
128+
```
129+
130+
### GitHub Pages Setup
131+
132+
The project uses GitHub Actions to automatically deploy documentation to GitHub Pages:
133+
134+
1. The workflow converts OpenAPI specs to SymbolGraph files
135+
2. DocC converts the SymbolGraph to HTML documentation
136+
3. The documentation is deployed to the `gh-pages` branch
137+
4. The landing page provides a user-friendly entry point to the technical documentation
138+
107139
## License
108140

109141
This project is licensed under the MIT License - see the LICENSE file for details.

‎docs/documentation.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -447,7 +447,7 @@ <h2>Technical Implementation</h2>
447447
<li>Rendering the documentation as HTML</li>
448448
</ol>
449449

450-
<a href="index.html" class="btn">View the API Documentation</a>
450+
<a href="/OpenAPI-integration-with-DocC/" class="btn">View the API Documentation</a>
451451

452452
<h2>Benefits of DocC Documentation</h2>
453453

‎index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -516,7 +516,7 @@
516516
<nav>
517517
<ul>
518518
<li><a href="https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC">GitHub</a></li>
519-
<li><a href="docs/documentation.html">Documentation</a></li>
519+
<li><a href="/OpenAPI-integration-with-DocC/">API Documentation</a></li>
520520
<li><a href="https://swift.org/documentation/docc/">DocC Resources</a></li>
521521
</ul>
522522
</nav>
@@ -535,7 +535,7 @@
535535
<div class="container">
536536
<h1>OpenAPI Integration with DocC</h1>
537537
<p>Transform OpenAPI specifications into beautiful, interactive documentation.</p>
538-
<a href="docs/documentation.html" class="btn">View Documentation</a>
538+
<a href="/OpenAPI-integration-with-DocC/" class="btn">View Documentation</a>
539539
<a href="https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC" class="btn btn-secondary">View on GitHub</a>
540540
<img src="docs/favicon.svg" alt="OpenAPI DocC graphic representation" class="hero-image" width="240">
541541
</div>
@@ -598,7 +598,7 @@ <h3>Auto-updating</h3>
598598
<img class="footer-logo" src="docs/favicon.svg" alt="OpenAPI DocC Logo" width="40">
599599
<div class="footer-links">
600600
<a href="https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC">GitHub</a>
601-
<a href="docs/documentation.html">Documentation</a>
601+
<a href="/OpenAPI-integration-with-DocC/">API Documentation</a>
602602
<a href="https://swift.org/documentation/docc/">DocC Resources</a>
603603
</div>
604604
<p class="copyright">Copyright © 2024 OpenAPI Integration with DocC. All rights reserved. Built using Swift DocC and OpenAPI.</p>

‎landing-page.html‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>OpenAPI Integration with DocC</title>
6+
<meta http-equiv="refresh" content="0; url=https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/docs/documentation.html">
7+
<style>
8+
body {
9+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
10+
margin: 0;
11+
padding: 20px;
12+
text-align: center;
13+
color: #333;
14+
background-color: #f5f5f7;
15+
height: 100vh;
16+
display: flex;
17+
flex-direction: column;
18+
justify-content: center;
19+
align-items: center;
20+
}
21+
22+
.container {
23+
max-width: 600px;
24+
margin: 0 auto;
25+
}
26+
27+
h1 {
28+
font-size: 24px;
29+
font-weight: 500;
30+
margin-bottom: 16px;
31+
}
32+
33+
p {
34+
font-size: 16px;
35+
line-height: 1.5;
36+
margin-bottom: 20px;
37+
}
38+
39+
a {
40+
color: #0066cc;
41+
text-decoration: none;
42+
font-weight: 500;
43+
}
44+
45+
a:hover {
46+
text-decoration: underline;
47+
}
48+
49+
.loader {
50+
border: 3px solid #f3f3f3;
51+
border-radius: 50%;
52+
border-top: 3px solid #0066cc;
53+
width: 30px;
54+
height: 30px;
55+
animation: spin 1s linear infinite;
56+
margin: 20px auto;
57+
}
58+
59+
@keyframes spin {
60+
0% { transform: rotate(0deg); }
61+
100% { transform: rotate(360deg); }
62+
}
63+
</style>
64+
</head>
65+
<body>
66+
<div class="container">
67+
<h1>OpenAPI Integration with DocC</h1>
68+
<p>Redirecting to the documentation page...</p>
69+
<div class="loader"></div>
70+
<p>If you are not redirected automatically, <a href="https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/docs/documentation.html">click here</a>.</p>
71+
</div>
72+
</body>
73+
</html>

0 commit comments

Comments
 (0)