Docs: Code Snippets Reliability

[arboleya]

Here are a few examples where the code snippets behave erratically:

1. • Sometimes code snippets are malformatted (indentation)
     • style: fixes docs-hub#226
     • https://docs.fuel.network/docs/nightly/fuels-ts/providers/
2. • Sometimes code snippets don't have syntax highlight
     • Syntax highlighting is not highlighting HTML docs-hub#227
     • https://docs.fuel.network/docs/nightly/fuels-ts/getting-started/#cdn-usage-browser-only
3. • Sometimes code snippets have "import" comments
     • TypeScript imports are not being rendered docs-hub#233
     • docs: validation for code snippet import statements #1980
     • https://docs.fuel.network/docs/nightly/fuels-ts/cookbook/custom-transactions/#custom-transactions
       • // #import { BN, CoinQuantityLike, ScriptTransactionRequest }
4. • Variables are not getting rendered
     • Versions not populating in code snippet (TS) docs-hub#229
     • https://docs.fuel.network/docs/nightly/fuels-ts/getting-started/#cdn-usage-browser-only
5. • Button "see code in context" doesn't work on the docs portal
     • Code in context button docs-hub#234
6. • Type imports are not being displays as type imports
     • docs: enable types in code snippets #2010

We should probably be considering getting rid of #context tags if possible.

All this points to the nightly version of the docs, currently at 0.77.

[petertonysmith94]

Summary

• Docs-hub pulls over our raw assets (.md and .test.ts), parses, and builds them.
• I've identified probable issues and tested their solutions (see below).
• Maintaining two documentations systems seems obsolete to me.

Investigation

1. Sometimes code snippets are malformatted (indentation)
   https://docs.fuel.network/docs/nightly/fuels-ts/providers/

Occurs during the fix-indent.ts process on the docs hub. Also appears to be a problem with the rust snippets.
https://docs.fuel.network/docs/nightly/fuels-rs/deploying/configurable-constants/
https://docs.fuel.network/docs/nightly/fuels-rs/predicates/send-spend-predicate/

I believe this is due to regex replacement conflicting. For all projects, languages and coding format.

• Simplify and separate this regex replacement by project + language, should alleviate this issue and lead to more predictable results.

---

2. Sometimes code snippets don't have syntax highlight
   • https://docs.fuel.network/docs/nightly/fuels-ts/getting-started/#cdn-usage-browser-only

There is no syntax highlighting configured for html or html-vue in the docs hub.

• The code snippet language changed from html-vue to html.
• Add html to the highlighter langs in the docs-hub.

---

3. Sometimes code snippets have "import" comments

• https://docs.fuel.network/docs/nightly/fuels-ts/cookbook/custom-transactions/#custom-transactions
  • // #import { BN, CoinQuantityLike, ScriptTransactionRequest }

Incorrect #import format. Should be: // #import { BN, CoinQuantityLike, ScriptTransactionRequest };

• Additional lint checking within fuels-ts.

---

4. Variables are not getting rendered

• https://docs.fuel.network/docs/nightly/fuels-ts/getting-started/#cdn-usage-browser-only

Variables not being detected. Potential solution:

• Changing equality check to includes on the conditions.

  tsBookVersions: (node: any) => {
    return (
      typeof node.value === 'string' &&
      (node.value.includes('{{fuels}}') ||
        node.value.includes('{{fuelCore}}') ||
        node.value.includes('{{forc}}')
      )
    );
  },

• Alter the node value directly before any other manipulation.

  visit(newTree, '', (node: any, idx, parent) => {
    if (conditions.tsBookVersions(node)) {
      node.value = node.value
        .replace('{{fuels}}', versions.FUELS)
        .replace('{{fuelCore}}', versions.FUEL_CORE)
        .replace('{{forc}}', versions.FORC);
    }
    ...
  })

---

5. Button "see code in context" doesn't work on the docs portal

• I believe this is a feature request within the docs-hub?

---

Side quest: We should probably be considering getting rid of #context tags if possible.

There are 54 instances of#context, 45+ should be pretty simple. Would be good to get people's ideas on the import, as I can't see a way to do it currently.
https://github.com/FuelLabs/fuels-ts/blob/master/apps/demo-typegen/src/demo.test.ts#L79

[petertonysmith94]

Moving this back to Queued and setting to blocked as awaiting docs-hub related work.

Keeping my name on for follow up purposes 😄

[arboleya]

Great job! Can't we close the issue as completed? 🙂

You did everything and created issues on the docs-hub repo for the remaining items.

[petertonysmith94]

That sounds like a better idea 🥇

[petertonysmith94]

Closing due to all issues within fuels-ts being resolved and associated docs-hub issues have been created.