Revisit snippet generation tooling for documentation

[maschad]

We experience different inconsistencies with docs-hub - such as FuelLabs/docs-hub#233 and FuelLabs/docs-hub#234 for example - that have created quite a bit of friction. We should perhaps revisit the tooling that we use to generate doc snippets.

The most popular option would probably be Docusaurus as it provides a more feature-rich experience out of the box. It has built-in support for versioning, localization, and search, while VitePress requires additional configuration or external tools for these features. Docusaurus also has a larger ecosystem and community support compared to VitePress.

We should at the very least think about localization as we currently only have support for English. Interested to hear others' thoughts

[arboleya]

IIRC, we also considered docsaurus at the beginning, but since vitepress already supports importing regions from text files, I think that's enough for now. The scope then extends to code snippets and their sometimes unreliable nature—for example, when using #context or #import tags. I may have some ideas to draft out and share with you guys.

[arboleya]

Endgoal TL;DR

1. Provide improved separation of concerns:
   1. raw snippets — fully working auto-executable snippets without regions or cuts
   2. wrapped snippets — wraps raw snippets with HOF at the post-build step or similar
   3. tests — usual unit tests, running against the [generated] wrapped snippets
2. Prohibits the use of code regions
3. Enforces one text file per code snippet
4. Snippets are testable and runnable in isolation

Summary

I'd say the #context and #import issues are the most pernicious obstacles to correctness and improved DX. We could remove regions from the equation and favor entire files, solving these problems altogether.

I'm also intrigued by running these snippets in isolation.

Could these two ideas converge?

Hypothesys

Consider a hypothetical snippet that can be:

1. displayed in the docs
2. copy + pasted + run locally
3. click + run online

// foobar.ts
import { Provider, Wallet, FUEL_NETWORK_URL } from 'fuels';

(async function main () {
  const address = 'fuel..leuf'; // consider the full address here

  const provider = await Provider.create(FUEL_NETWORK_URL);
  const assetId = provider.getBaseAssetId();
  const balance = await Wallet.fromAddress(address, provider).getBalance(assetId);

  console.log(balance);
})();

Test Assertions

How could we ensure that these self-executing functions are working?

1. Create .snippets.ts duplicates wrapped in high-order functions (HOF)
2. Inject console.log capturing hook somehow (just as a )
3. Write unit tests that target the generated file instead (see below)

Let's say that on post-build the generated file would look like this:

Mind the prepended export const main = () => HOF.

// foobar.snippet.ts
import { Provider, Wallet, FUEL_NETWORK_URL } from 'fuels';

export const main = () => (async function () {
  const address = 'fuel..leuf'; // consider the full address here

  const provider = await Provider.create(FUEL_NETWORK_URL);
  const assetId = provider.getBaseAssetId();
  const balance = await Wallet.fromAddress(address, provider).getBalance(assetId);

  console.log(balance);
})();

Then we could have tests like this asserting the wrapped snippets, not the raw ones:

// imports wrapped snippet
import { main } from './foobar.snippet.ts';

test('..', () => {
  const res = await main();
  expect(res.logCalls[0]).toEqual(..);
});

Final Snapshot

In the end, we'd have:

1. snippets/src/foobar.ts
2. snippets/src/foobar.snisppet.ts (generated, ignored)
3. snippets/src/foobar.test.ts

They'd contain, respectively:

1. The raw snippet to be shown somewhere (maybe also run?)
2. The wrapped snippet that tests will use
3. The tests themselves

Final Considerations

1. What problems will removing #context and #import solve, and how would it improve DX?

   • It would remove static strings that can go outdated. At the same time, the new model may provide a better DX by offering fully working and auto-executable snippets that one can test, run, and plug into other flows.

2. How would the injection of the console.log capturing hook work, and what would be its purpose?

   • It would collect the arguments for every log call and return them somehow. Then, unit tests could iterate and assert over them. Please remember that these unit tests would be only concerned with the snippet's output — not their underlying functionality. I'd assume we could even have single-assertion tests for most snippets, which could be easier to maintain.

3. What would be the benefits of having the raw snippet, the wrapped snippet, and the tests in separate files, and how would that improve the project's workflow?

   • This separation of concerns combines all the good parts mentioned above. It gives the ability and confidence to provide helpful snippets that can be used as building blocks, perhaps even without relying on the see code in context button, which is currently not implemented in our docs.

[arboleya]

The demarcation is a trivial thing, and it's not even an issue.

Pure and plain snippets are easier to use, port, and run elsewhere.

They should not be tied with anything (tests, esm custom options, etc).

[nedsalk]

I don't fully understand the snippet content of your proposal. How would it be shown to the user on the docs? Wrapped as an IIFE so that it can be copy-pasted and ran right way, or would its content be extracted to show only the body?

[arboleya]

Initially, I considered showing it whole, although adding the IFFE brought noise into the party.

The thing about ideals is that once we find a solution to a problem, it usually creates another problem.

[petertonysmith94]

The demarcation is a trivial thing, and it's not even an issue.

Pure and plain snippets are easier to use, port, and run elsewhere.

They should not be tied with anything (tests, ESM custom options, etc).

A pure and plain snippet, will also alleviate a lot of the issues that we experience with docs-hub not being quite aligned with our documentation as mentioned FuelLabs/docs-hub#233 and FuelLabs/docs-hub#234.

From what I can tell, this would allow the docs-hub to be able to use our snippets as is, therefore reducing the need for transforming (which has been a source of our problems currently).

---

I would be nice to not have to generate an intermediary snippet (snippets/src/foobar.snippet.ts).

It's worth creating a couple samples solutions, and analysing their pro's and con's.

[arboleya]

@petertonysmith94 Here's a simple PoC:

• https://github.com/arboleya/docs-widgets

@nedsalk The constraints are the necessary configurations for using top-level await.

[petertonysmith94]

I believe this discussion is now closed - we have the following issue:

• Revamp code-snippets #2504

Please reopen if this asssesment is incorrect 😄