How to auto-format code snippets in documentation with Carbon and GPT-3.5

Hey there, fellow developers! Ever found yourself staring at raw code snippets in your documentation, wishing they looked more polished and professional? Well, you’re in luck! In this guide, I’ll walk you through a simple yet effective way to transform those plain code snippets into beautifully formatted images using Carbon and GPT-3.5. And the best part? You can set this up in about 30 minutes, even if you’re just starting out. Let’s dive in!

Introduction

Documentation is the backbone of any project, and well-presented code snippets can make a world of difference. They not only enhance readability but also add a touch of professionalism to your docs and blog posts. By automating the process of converting raw code into formatted images, you can save time and ensure consistency across your documentation. We’ll be leveraging two powerful tools: Carbon for generating the images and GPT-3.5 for processing and refining our code snippets.

Step-by-Step Guide

Step 1: Set Up Your OpenAI Account and Obtain API Key

First things first, you’ll need access to OpenAI’s GPT-3.5 API.

• Head over to the OpenAI website and sign up for an account.
• Once registered, navigate to the API section to generate a new API key. This key will be your gateway to interacting with GPT-3.5.
• Store this key securely; you’ll need it in the upcoming steps.

For a detailed walkthrough, check out this guide on obtaining a ChatGPT developer account and API keys.

Step 2: Choose Your Automation Platform

To automate the workflow, we’ll use an automation platform like Zapier or Make (formerly Integromat). Both platforms offer intuitive interfaces and a plethora of integrations.

• Zapier: Known for its user-friendly design and extensive app integrations.
• Make: Offers advanced features and flexibility, suitable for more complex workflows.

For this guide, I’ll use Zapier, but the steps are quite similar for Make.

Step 3: Set Up a Trigger in Zapier

We’ll start by setting up a trigger that initiates the workflow whenever a new code snippet is added.

• Log in to your Zapier account and click on “Create Zap.”
• Choose a trigger app. For instance, if you’re using Google Sheets to store your code snippets, select Google Sheets.
• Set the trigger event to “New Row” (or the equivalent for your chosen app).
• Connect your account and specify the spreadsheet and worksheet where your code snippets will be added.

Step 4: Process the Code Snippet with GPT-3.5

Next, we’ll use GPT-3.5 to process and refine the code snippet.

• Add a new action in Zapier and select the “Webhooks by Zapier” app.
• Choose the “POST” action event.
• In the setup, configure the following:
  • URL: https://api.openai.com/v1/chat/completions
  • Headers:
    • Authorization: Bearer YOUR_OPENAI_API_KEY
    • Content-Type: application/json
  • Data:

    {
      "model": "gpt-3.5-turbo",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant that formats code snippets for documentation."
        },
        {
          "role": "user",
          "content": "Format the following code snippet:\n\n{{CodeSnippet}}"
        }
      ],
      "temperature": 0.7,
      "max_tokens": 150
    }
            

Replace {{CodeSnippet}} with the actual code snippet from your trigger.

For more details on making API requests to GPT-3.5, refer to this ChatGPT API documentation.

Step 5: Generate the Formatted Image with Carbon

Now, we’ll use Carbon to create a beautifully formatted image of the code snippet.

• Add another action in Zapier and select the “Webhooks by Zapier” app.
• Choose the “POST” action event.
• In the setup, configure the following:
  • URL: https://carbon.now.sh/api/image
  • Headers:
    • Content-Type: application/json
  • Data:

    {
      "code": "{{FormattedCode}}",
      "theme": "seti",
      "language": "auto",
      "exportSize": "2x",
      "windowControls": true,
      "widthAdjustment": true,
      "paddingVertical": "56px",
      "paddingHorizontal": "56px"
    }
            

Replace {{FormattedCode}} with the output from the GPT-3.5 step.

Note: As of now, Carbon doesn’t offer an official API. The above URL is a workaround and may be subject to change. Always refer to the latest Carbon documentation for updates.

Step 6: Save the Generated Image

Finally, we’ll save the generated image to a storage service like Google Drive.

• Add a new action in Zapier and select the “Google Drive” app.
• Choose the “Upload File” action event.
• Connect your Google Drive account.
• In the setup, configure the following:
  • File: Use the image URL from the Carbon step.
  • Folder: Specify the folder where you want to save the images.
  • File Name: Set a dynamic name, e.g., FormattedCodeSnippet_{{Timestamp}}.

Optional Enhancements

Once you’ve got the basic workflow up and running, here are a few quick wins to enhance it:

• Automate Sharing: Add a step to automatically share the generated images on your social media platforms or embed them into your blog posts.
• Customize Themes: Experiment with different Carbon themes to match your brand’s aesthetics.
• Error Handling: Implement error handling steps to notify you if any part of the automation fails, ensuring you can address issues promptly.

And there you have it! With this setup, you can effortlessly convert raw code snippets into beautifully formatted images, elevating the quality of your documentation and blog posts. Happy coding!