Opinion: DevRel Is a Waste of Money for 70% of Companies – Use Documentation Instead

import os
import sys
import json
import shutil
from pathlib import Path
import subprocess
from typing import Dict, List, Optional

# Configuration constants for docs generation pipeline
OPENAPI_SPEC_PATH = Path("./openapi/v1/openapi.json")
DOCS_OUTPUT_DIR = Path("./docs/_build/html")
SPHINX_CONF_DIR = Path("./docs")
VERSION_TAG = os.getenv("GIT_VERSION", "latest")
ERROR_LOG_PATH = Path("./docs-generation-error.log")

def log_error(message: str) -> None:
    """Append error messages to persistent log file for CI debugging."""
    with open(ERROR_LOG_PATH, "a") as f:
        f.write(f"[ERROR] {message}\n")
    print(f"[ERROR] {message}", file=sys.stderr)

def validate_openapi_spec(spec_path: Path) -> Optional[Dict]:
    """Load and validate OpenAPI spec, return parsed dict or None on failure."""
    if not spec_path.exists():
        log_error(f"OpenAPI spec not found at {spec_path}")
        return None
    try:
        with open(spec_path, "r") as f:
            spec = json.load(f)
        # Basic OpenAPI 3.x validation
        if spec.get("openapi", "").startswith("3.") is False:
            log_error(f"Unsupported OpenAPI version: {spec.get('openapi')}")
            return None
        if "paths" not in spec:
            log_error("OpenAPI spec missing required 'paths' field")
            return None
        return spec
    except json.JSONDecodeError as e:
        log_error(f"Invalid JSON in OpenAPI spec: {e}")
        return None
    except Exception as e:
        log_error(f"Unexpected error loading spec: {e}")
        return None

def generate_sphinx_docs(spec: Dict, version: str) -> bool:
    """Generate versioned Sphinx docs from OpenAPI spec."""
    # Create versioned output directory
    versioned_output = DOCS_OUTPUT_DIR / version
    versioned_output.mkdir(parents=True, exist_ok=True)

    # Write OpenAPI spec to Sphinx source dir for reference
    sphinx_source = SPHINX_CONF_DIR / "source"
    sphinx_source.mkdir(exist_ok=True)
    with open(sphinx_source / "openapi.json", "w") as f:
        json.dump(spec, f, indent=2)

    # Run Sphinx build with error handling
    try:
        result = subprocess.run(
            ["sphinx-build", "-b", "html", str(sphinx_source), str(versioned_output)],
            check=True,
            capture_output=True,
            text=True
        )
        print(f"[SUCCESS] Sphinx build completed for version {version}")
        return True
    except subprocess.CalledProcessError as e:
        log_error(f"Sphinx build failed: {e.stderr}")
        return False
    except FileNotFoundError:
        log_error("Sphinx not installed. Run 'pip install sphinx sphinx-openapi'")
        return False

def main() -> int:
    """Main entry point for docs generation pipeline."""
    print(f"Starting docs generation for version: {VERSION_TAG}")

    # Step 1: Validate OpenAPI spec
    spec = validate_openapi_spec(OPENAPI_SPEC_PATH)
    if spec is None:
        return 1

    # Step 2: Generate docs
    success = generate_sphinx_docs(spec, VERSION_TAG)
    if not success:
        return 1

    # Step 3: Clean up old versions (keep last 3)
    existing_versions = sorted([d.name for d in DOCS_OUTPUT_DIR.iterdir() if d.is_dir()], reverse=True)
    for old_version in existing_versions[3:]:
        shutil.rmtree(DOCS_OUTPUT_DIR / old_version)
        print(f"Cleaned up old version: {old_version}")

    return 0

if __name__ == "__main__":
    sys.exit(main())

import os
import pandas as pd
import numpy as np
from datetime import datetime, timedelta
from typing import List, Dict, Optional
import sys

# Configuration for DevRel spend audit
SPEND_CSV_PATH = Path("./devrel_spend_2023.csv")
PIPELINE_CSV_PATH = Path("./pipeline_attribution_2023.csv")
OUTPUT_REPORT_PATH = Path("./devrel_roi_report.html")
DATE_COL = "transaction_date"
ATTRIBUTION_COL = "attributed_pipeline"
SPEND_COL = "spend_usd"
CHANNEL_COL = "channel"

# Valid DevRel channels to audit (exclude docs spend)
DEVREL_CHANNELS = ["conference_sponsorship", "devrel_salary", "webinar_hosting", "swag", "community_event"]

def load_and_validate_data(spend_path: Path, pipeline_path: Path) -> Optional[Dict[str, pd.DataFrame]]:
    """Load and validate spend and pipeline CSVs, return dict of dataframes or None."""
    if not spend_path.exists():
        print(f"[ERROR] Spend CSV not found at {spend_path}", file=sys.stderr)
        return None
    if not pipeline_path.exists():
        print(f"[ERROR] Pipeline CSV not found at {pipeline_path}", file=sys.stderr)
        return None

    try:
        # Load spend data
        spend_df = pd.read_csv(spend_path, parse_dates=[DATE_COL])
        required_spend_cols = [DATE_COL, SPEND_COL, CHANNEL_COL, "description"]
        missing_spend = [col for col in required_spend_cols if col not in spend_df.columns]
        if missing_spend:
            print(f"[ERROR] Spend CSV missing columns: {missing_spend}", file=sys.stderr)
            return None

        # Load pipeline data
        pipeline_df = pd.read_csv(pipeline_path, parse_dates=[DATE_COL])
        required_pipeline_cols = [DATE_COL, ATTRIBUTION_COL, CHANNEL_COL, "lead_id"]
        missing_pipeline = [col for col in required_pipeline_cols if col not in pipeline_df.columns]
        if missing_pipeline:
            print(f"[ERROR] Pipeline CSV missing columns: {missing_pipeline}", file=sys.stderr)
            return None

        return {"spend": spend_df, "pipeline": pipeline_df}
    except pd.errors.EmptyDataError:
        print("[ERROR] CSV file is empty", file=sys.stderr)
        return None
    except Exception as e:
        print(f"[ERROR] Failed to load data: {e}", file=sys.stderr)
        return None

def calculate_roi_metrics(spend_df: pd.DataFrame, pipeline_df: pd.DataFrame) -> pd.DataFrame:
    """Calculate ROI metrics per DevRel channel, filter non-DevRel spend."""
    # Filter to only DevRel channels
    devrel_spend = spend_df[spend_df[CHANNEL_COL].isin(DEVREL_CHANNELS)].copy()
    devrel_pipeline = pipeline_df[pipeline_df[CHANNEL_COL].isin(DEVREL_CHANNELS)].copy()

    # Aggregate spend by channel (monthly)
    devrel_spend["month"] = devrel_spend[DATE_COL].dt.to_period("M")
    monthly_spend = devrel_spend.groupby(["channel", "month"])[SPEND_COL].sum().reset_index()

    # Aggregate pipeline by channel (monthly)
    devrel_pipeline["month"] = devrel_pipeline[DATE_COL].dt.to_period("M")
    monthly_pipeline = devrel_pipeline.groupby(["channel", "month"])[ATTRIBUTION_COL].sum().reset_index()

    # Merge spend and pipeline
    merged = pd.merge(monthly_spend, monthly_pipeline, on=["channel", "month"], how="left")
    merged[ATTRIBUTION_COL] = merged[ATTRIBUTION_COL].fillna(0)

    # Calculate ROI (pipeline per dollar spent)
    merged["roi"] = merged[ATTRIBUTION_COL] / merged[SPEND_COL]
    merged["roi"] = merged["roi"].replace([np.inf, -np.inf], np.nan)

    return merged

def generate_html_report(metrics_df: pd.DataFrame) -> None:
    """Generate HTML report with ROI metrics, highlight low-performing channels."""
    # Calculate summary stats
    total_spend = metrics_df[SPEND_COL].sum()
    total_pipeline = metrics_df[ATTRIBUTION_COL].sum()
    avg_roi = metrics_df["roi"].mean()

    # Generate HTML
    html_content = f"""



        2023 DevRel Spend ROI Report
        Total DevRel Spend: ${total_spend:,.2f}
        Total Attributed Pipeline: ${total_pipeline:,.2f}
        Average ROI (Pipeline per Dollar): ${avg_roi:,.2f}

            {''.join([f"" for _, row in metrics_df.iterrows()])}

            ChannelMonthSpendPipelineROI{row['channel']}{row['month']}${row[SPEND_COL]:,.2f}${row[ATTRIBUTION_COL]:,.2f}${row['roi']:,.2f}


    """

    with open(OUTPUT_REPORT_PATH, "w") as f:
        f.write(html_content)
    print(f"[SUCCESS] Report generated at {OUTPUT_REPORT_PATH}")

def main() -> int:
    print("Starting DevRel spend audit...")
    data = load_and_validate_data(SPEND_CSV_PATH, PIPELINE_CSV_PATH)
    if data is None:
        return 1

    metrics = calculate_roi_metrics(data["spend"], data["pipeline"])
    generate_html_report(metrics)

    # Print low-performing channels (ROI < $1 per dollar spent)
    low_performers = metrics[metrics["roi"] < 1]
    if not low_performers.empty:
        print("\n[WARNING] Low-performing channels (ROI < $1 per $1 spent):")
        print(low_performers[["channel", "month", "roi"]].to_string(index=False))

    return 0

if __name__ == "__main__":
    sys.exit(main())

import React, { useState, useEffect } from 'react';
import { OpenAPIClientAxios } from 'openapi-client-axios';
import { Alert, Spinner, Table, Form, Button } from 'react-bootstrap';
import 'bootstrap/dist/css/bootstrap.min.css';

// Configuration for API docs explorer
const OPENAPI_SPEC_URL = process.env.REACT_APP_OPENAPI_SPEC_URL || '/openapi/v1/openapi.json';
const API_BASE_URL = process.env.REACT_APP_API_BASE_URL || 'https://api.example.com';

// Types for OpenAPI spec structure
interface OpenAPIPath {
  summary?: string;
  description?: string;
  get?: OpenAPIOperation;
  post?: OpenAPIOperation;
  put?: OpenAPIOperation;
  delete?: OpenAPIOperation;
}

interface OpenAPIOperation {
  operationId: string;
  summary?: string;
  description?: string;
  parameters?: Array<{ name: string; in: string; required: boolean; schema: any }>;
  requestBody?: any;
  responses: Record;
}

interface APIDocsExplorerProps {
  initialVersion?: string;
}

const APIDocsExplorer: React.FC = ({ initialVersion = 'latest' }) => {
  // State variables
  const [spec, setSpec] = useState | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const [selectedPath, setSelectedPath] = useState(null);
  const [selectedMethod, setSelectedMethod] = useState('get');
  const [requestParams, setRequestParams] = useState>({});
  const [response, setResponse] = useState(null);
  const [responseError, setResponseError] = useState(null);

  // Fetch OpenAPI spec on component mount
  useEffect(() => {
    const fetchSpec = async () => {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch(OPENAPI_SPEC_URL);
        if (!response.ok) {
          throw new Error(`Failed to load OpenAPI spec: ${response.statusText}`);
        }
        const specData = await response.json();
        // Basic validation
        if (!specData.paths || !specData.openapi) {
          throw new Error('Invalid OpenAPI spec: missing paths or openapi version');
        }
        setSpec(specData);
        // Select first path by default
        const firstPath = Object.keys(specData.paths)[0];
        if (firstPath) {
          setSelectedPath(firstPath);
          const methods = Object.keys(specData.paths[firstPath]).filter(m => ['get', 'post', 'put', 'delete'].includes(m));
          if (methods.length > 0) setSelectedMethod(methods[0]);
        }
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Unknown error loading spec');
      } finally {
        setLoading(false);
      }
    };
    fetchSpec();
  }, [initialVersion]);

  // Handle API request execution
  const executeRequest = async () => {
    if (!selectedPath || !spec) return;
    setResponse(null);
    setResponseError(null);
    try {
      const api = new OpenAPIClientAxios({ definition: spec, baseURL: API_BASE_URL });
      const client = await api.init();
      const pathItem = spec.paths[selectedPath];
      const operation = pathItem[selectedMethod];
      if (!operation) throw new Error(`No ${selectedMethod} operation for path ${selectedPath}`);
      // Build request config
      const config: any = {};
      if (selectedMethod === 'get' || selectedMethod === 'delete') {
        config.params = requestParams;
      } else {
        config.data = requestParams;
      }
      // Execute request
      const result = await client[operation.operationId](config);
      setResponse(result.data);
    } catch (err) {
      setResponseError(err instanceof Error ? err.message : 'Request failed');
    }
  };

  // Handle parameter input change
  const handleParamChange = (paramName: string, value: any) => {
    setRequestParams(prev => ({ ...prev, [paramName]: value }));
  };

  // Render loading state
  if (loading) {
    return (


          Loading API docs...


    );
  }

  // Render error state
  if (error) {
    return (

        Error Loading API Docs
        {error}

    );
  }

  // Render main explorer
  return (

      Interactive API Docs Explorer
      Version: {spec?.info?.version || initialVersion}


        {/* Path and method selector */}

          Endpoints
           setSelectedPath(e.target.value)}
            className="mb-3"
          >
            {spec?.paths && Object.keys(spec.paths).map(path => (
              {path}
            ))}


           setSelectedMethod(e.target.value)}
            className="mb-3"
          >
            {selectedPath && spec?.paths[selectedPath] && 
              Object.keys(spec.paths[selectedPath])
                .filter(m => ['get', 'post', 'put', 'delete'].includes(m))
                .map(method => (
                  {method.toUpperCase()}
                ))}



        {/* Request parameters and execution */}

          Request
          {selectedPath && spec?.paths[selectedPath]?.[selectedMethod]?.parameters?.map(param => (

              {param.name} {param.required && *}
               handleParamChange(param.name, e.target.value)}
              />
              {param.description}

          ))}


            Execute Request


          {/* Response section */}
          Response
          {responseError && {responseError}}
          {response && (
                          {JSON.stringify(response, null, 2)}

          )}



  );
};

export default APIDocsExplorer;

// algolia-docsearch.config.js
export default {
  index_name: 'my-api-docs',
  start_urls: [
    'https://docs.example.com/v1/',
    'https://docs.example.com/v2/',
    'https://docs.example.com/v3/',
  ],
  stop_urls: ['https://docs.example.com/v1/deprecated/'],
  selectors: {
    lvl0: '.docs-version',
    lvl1: '.docs-title',
    lvl2: '.docs-heading',
    lvl3: '.docs-subheading',
    text: '.docs-content p, .docs-content li',
  },
  nb_hits: 5000,
};

# .github/workflows/docs.yml
name: Generate and Deploy Docs
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      - name: Generate OpenAPI spec
        run: go run cmd/generate-openapi/main.go > openapi/v1/openapi.json
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install Sphinx
        run: pip install sphinx sphinx-openapi
      - name: Build docs
        run: sphinx-build -b html docs/source docs/_build/html
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

  SwaggerUIBundle({
    url: '/openapi/v1/openapi.json',
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: 'BaseLayout',
    supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
    onComplete: () => {
      // Pre-populate API key for docs users
      const apiKey = prompt('Enter your API key (or generate one at /dashboard)');
      if (apiKey) {
        ui.preauthorizeApiKey('apiKey', apiKey);
      }
    }
  });