Add chunking comments to the snippets

[Chen Hui Jing]

After some minor research, these are the comment syntaxes used by various languages:

Comment	Language
//	Javascript C# Go C C++ PHP Java Kotlin Swift TypeScript Rust Scala
#	Python Ruby R Perl Elixir
`	VB.NET
%	ErLang
--	Haskell
	HTML
/.../	CSS

As such, I think using something that starts with double slashes is a reasonable choice for the TS files. The next thought is that we don't necessarily need to have a comment syntax that works for every language in the world because when the new language's snippets get written, they can use a comment syntax appropriate to that language.

Like, when we start writing Python snippets (if ever), we can do something like #-@! or whatever, as long as it starts with #.

Anyway, my proposed syntax for ease of identifying is //@! because again, I want the double slash to prevent the code from borking out for now on Typescript code. I have tested my chunked code component in a test repository with the following modified full code snippet file:

//@! start chunk 1 | title=Import dependencies
import dotenv from "dotenv";
import { join } from "path";
import { createAuthenticatedClient, isPendingGrant } from "@interledger/open-payments";
import { loadPrivateKey } from "utils/load-private-key";

dotenv.config({ path: join(__dirname, "..", ".env") });

const KEY_ID = process.env.KEY_ID;
const PAYMENT_POINTER = process.env.PAYMENT_POINTER;
//@! end chunk 1

async function run() {
//@! start chunk 2 | title=Initialize Open Payments client
    const client = await createAuthenticatedClient({
        paymentPointerUrl: PAYMENT_POINTER,
        privateKey: loadPrivateKey(),
        keyId: KEY_ID,
    });
//@! end chunk 2
//@! start chunk 3 | title=Get payment pointer information
    const paymentPointer = await client.paymentPointer.get({
        url: PAYMENT_POINTER,
    });
//@! end chunk 3
//@! start chunk 4 | title=Request incoming payment grant
    const grant = await client.grant.request(
        {
            url: paymentPointer.authServer,
        },
        {
            access_token: {
                access: [
                    {
                        type: "incoming-payment",
                        actions: ["list", "list-all", "read", "read-all", "complete", "create"],
                    },
                ],
            },
        },
    );

    if (isPendingGrant(grant)) {
        throw new Error("Expected non-interactive grant");
    }

    console.log("INCOMING_PAYMENT_ACCESS_TOKEN =", grant.access_token.value);
    console.log("INCOMING_PAYMENT_ACCESS_TOKEN_MANAGE_URL = ", grant.access_token.manage);
//@! end chunk 4
}

run();

The ideal code snippet to make my component work properly is that the code between each chunk must be programmatically correct. This is because I am using Prettier to deal with the extra indentation that arises from extracting code between functions. Prettier will break the build if the code doesn't work properly, i.e. if there is an extra bracket or something.

I included "chunk X" purely as a human-readable convenience feature so our tech writing team doesn't have to manually count which chunk they want to be writing about in the docs. They can conserve their braincells for more important things.

Anyway, the prototype can be seen here:
Our tech writers will also be able to add whatever text they want between each chunk. The API for the <ChunkedSnippet> component is as follows:

Use this component on specially formatted code snippet files from a public Github repository to be displayed as code. The code files must have "chunking comments" to allow the component to work correctly without borking out the whole site.

It takes a source attribute which must be a raw Github link, and a chunk attribute which specifies which chunk you want to display. To use it, your docs page must be in .mdx format. Please change the format from .md to .mdx if necessary. All your existing markdown will still be supported without issue. Import the ChunkedSnippet component like so:

import ChunkedSnippet from '/src/components/ChunkedSnippet.astro'

Use the <ChunkedSnippet> component within your content like so:

<ChunkedSnippet
  source='https://raw.githubusercontent.com/huijing/filerepo/gh-pages/incoming-grant.ts'
  chunk='1'
/>

You can preview the output of this new component at: https://deploy-preview-300--openpayments-preview.netlify.app/dinosaur/

[Chen Hui Jing]

Closed by c14c5c4