Set up GitHub Pages for documentation hosting

Author: ayushshrivastv

.github/workflows/pages.yml

@@ -0,0 +1,34 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1 

README.md

@@ -1,74 +1,95 @@
-# OpenAPI to DocC Symbol Graph
+# OpenAPI Integration with DocC
 
-A tool to convert OpenAPI documents into DocC symbol graphs, enabling seamless integration of API documentation with Swift's DocC documentation system.
+This project provides tools and examples for integrating OpenAPI specifications with Apple's DocC documentation system. It allows developers to create beautiful, interactive documentation for REST APIs that matches the style and quality of Swift API documentation.
 
-## Features
+## Overview
 
-- Converts OpenAPI documents (JSON/YAML) to DocC symbol graphs
-- Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
-- Generates comprehensive documentation for:
-  - API endpoints
-  - Request parameters
-  - Request bodies
-  - Response types
-- Preserves OpenAPI descriptions and metadata
-- Command-line interface for easy integration
+OpenAPI is the industry standard for documenting HTTP services, but Swift developers are already familiar with DocC for their Swift and Objective-C API documentation. This project bridges that gap by converting OpenAPI specifications into a format that DocC can understand and render.
 
-## Installation
+## Key Features
 
-### Requirements
+- Convert OpenAPI 3.1.0 specifications to DocC-compatible format
+- Generate beautiful API documentation
+- Provide a consistent documentation experience for Swift developers
+- Support for documenting endpoints, schemas, parameters, and more
 
-- Swift 5.7 or later
-- macOS 12.0 or later
+## Getting Started
 
-### Building from Source
+### Prerequisites
+
+- Xcode 15.0 or later
+- Swift 6.0 or later
+- Python 3 (for local documentation serving)
+
+### Installation
 
-1. Clone the repository:
 ```bash
-git clone https://github.com/yourusername/OpenAPItoSymbolGraph.git
-cd OpenAPItoSymbolGraph
+git clone https://github.com/ayushshrivastv/OpenAPI-integration-with-DocC.git
+cd OpenAPI-integration-with-DocC
+swift build
 ```
 
-2. Build the package:
+### Usage
+
+1. Convert your OpenAPI specification to a SymbolGraph:
+
 ```bash
-swift build -c release
+swift run openapi-to-symbolgraph path/to/your/api.yaml --output-path api.symbolgraph.json
 ```
 
-3. The executable will be available at `.build/release/openapi-to-symbolgraph`
+2. Create a DocC documentation catalog (see `API.docc` as an example)
 
-## Usage
+3. Generate the documentation:
 
 ```bash
-openapi-to-symbolgraph <input-path> [--output-directory <directory>] [--output-file <filename>]
+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
 ```
 
-### Arguments
+## Viewing the Documentation
+
+### Online Documentation
+
+The latest documentation is automatically deployed to GitHub Pages and can be viewed at:
+
+[https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/)
+
+### Local Documentation Server
 
-- `input-path`: Path to the OpenAPI document (JSON or YAML)
-- `--output-directory`: Directory where the symbol graph will be saved (default: current directory)
-- `--output-file`: Name of the output file (default: openapi.symbolgraph.json)
+You can serve the documentation locally using one of these methods:
 
-### Example
+#### Using the helper script:
 
 ```bash
-openapi-to-symbolgraph api.yaml --output-directory docs --output-file api.symbolgraph.json
+./serve-docs.sh
 ```
 
-## Integration with DocC
+#### Using Python 3 directly:
 
-1. Generate the symbol graph:
 ```bash
-openapi-to-symbolgraph api.yaml
+python3 -m http.server 8000 --directory docs
 ```
 
-2. Add the symbol graph to your DocC documentation:
-```swift
-import DocC
+Then open your browser to http://localhost:8000
 
-let documentation = Documentation(
-    symbolGraphs: ["openapi.symbolgraph.json"]
-)
-```
+## Example
+
+Check out the `DocsExample` directory for a working example of a REST API documented with DocC. It showcases how endpoints, schemas, and examples appear in the DocC format.
+
+## How It Works
+
+1. The OpenAPI specification is parsed using `OpenAPIKit`
+2. The specification is converted to a SymbolGraph, which is the format DocC uses for documentation
+3. DocC processes the SymbolGraph and generates the documentation
+4. The documentation can be served as a static website or deployed to GitHub Pages
+
+## GitHub Pages Deployment
+
+This repository is configured to automatically deploy documentation to GitHub Pages whenever changes are pushed to the main branch. The deployment process:
+
+1. Uses the GitHub Actions workflow defined in `.github/workflows/pages.yml`
+2. Takes the contents of the `docs` directory
+3. Deploys them to GitHub Pages
+4. Makes the documentation available at the URL: [https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/](https://ayushshrivastv.github.io/OpenAPI-integration-with-DocC/)
 
 ## Contributing
 

docs/.nojekyll

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Page Not Found - API Documentation</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+            line-height: 1.6;
+            color: #333;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 40px 20px;
+            text-align: center;
+        }
+        h1 {
+            color: #0066cc;
+            font-size: 36px;
+            margin-bottom: 20px;
+        }
+        p {
+            font-size: 18px;
+            margin-bottom: 30px;
+        }
+        a {
+            color: #0066cc;
+            text-decoration: none;
+        }
+        a:hover {
+            text-decoration: underline;
+        }
+    </style>
+</head>
+<body>
+    <h1>Page Not Found</h1>
+    <p>The documentation page you're looking for doesn't exist or has been moved.</p>
+    <p><a href="/OpenAPI-integration-with-DocC/">Return to Documentation Home</a></p>
+</body>
+</html> 

docs/404.html

@@ -0,0 +1,2 @@
+baseurl: "/OpenAPI-integration-with-DocC"
+url: "https://ayushshrivastv.github.io" 

docs/_config.yml

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Script to serve the documentation locally
+
+# Check if python3 is available
+if command -v python3 &> /dev/null; then
+    echo "Starting server with python3..."
+    python3 -m http.server 8000 --directory docs
+# Check if python is available as a fallback
+elif command -v python &> /dev/null; then
+    # Check Python version to ensure it's Python 3
+    PYTHON_VERSION=$(python --version 2>&1)
+    if [[ $PYTHON_VERSION == *"Python 3"* ]]; then
+        echo "Starting server with python..."
+        python -m http.server 8000 --directory docs
+    else
+        echo "Error: Python 3 is required to run the server."
+        exit 1
+    fi
+else
+    echo "Error: Python 3 is not installed. Please install Python 3 to run the server."
+    exit 1
+fi