feat: add better documentation features and convert from Rust repo

[camsjams]

Closes #548

How to view these updated docs

1. Basic Viev

Browse the repo on GitHub or local using the markdown files

2. Recommended View

Browse the docs using Jekyll (bundle exec jekyll serve) to see how they will appear on GitHub when deployed, which matches current docs here

Notable features

The docs will always report what versions of Fuels/Sway/Fuel Core they were built with:

New Guide section:

Embedded code using real code from library and unit tests:

Notes

• The format and chapters added are sourced from the Rust SDK Docs and adjusted as needed
• 99% of code examples are sourced from unit tested code, this took a while 😓 (see code snippets in action right here for example)
• Some docs were excluded from the docs as the Rust concepts didn't apply
• I added some new Docs and code snippets as needed
• I added the new AbiCoder for B512 as it was needed for an example 😅
• I ended up making a new plugin for Typedoc 😅 that copies the docs/_guide source folder into docs/guide and also pulls in code samples from repo as needed using syntaxt inspired by other Doc tools in other languages (and the Typedoc code block plugin which wasn't working well enough for our needs).
• the Jekyll data variables defined here are pulling in environment vars passed here which were originally parsed out in this code here
• Finally, this is not exhaustive, but is exhausting. We should get this proofread and code checked and then plan to add more pages in new PRs, and also aim to get this new version out to prod ASAP

[digorithm]

Alright y'all, let's get this out.

It's looking pretty solid; lots to improve but we got most of it good enough for a first release.

[camsjams]

There are two parts to the fuels-ts repository documentation

Part One: Typedoc

typedoc does the work of gathering all types, functions, classes, etc. from all of our source code. It will read through the packages folder and collect all that information and convert it into a markdown file, modifying the contents of docs/packages.

Furthermore, I've enhanced typedoc to also build out the Guide documentation with a custom plugin called typedoc-plugin-guide-builder that's in our repo here (We should move this to a standalone plugin later on). This portion of the typedoc process takes source files from docs/_guide, runs them through the plugins and renders code snippets pulled from source code.

How does the typedoc-plugin-guide-builder plugin work?

See how this markdown document refers to Sway and TypeScript code (also note the language hints like [@code:rust], and then see how reference in the TypeScript code is written

It writes the final results to docs/guide.

Intermission: Repo

Once typedoc is done generating the markdown docs, the data inside docs/packages and docs/guide are highly useful. These are complete docs that are checked into the repo and can be found alongside the code for TS-SDK consumers. One could view and use them just fine inside GitHub file browser or locally within their own filesystem.

Part Two: Jekyll

jekyll does the work of rendering the docs in markdown into something the browser understands: HTML. There are currently some open issues to possibly switch off Jekyll. We shall see, but GitHub pages uses Jekyll so its the easy choice for now.

Anyways, Jekyll is configured with the just the docs theme (actually a modified version of it found here within Fuels org). The only interesting thing to point out here is also that we update this file _data/versions.yml on each successful build to master, so that the versions rendered in the docs are accurate relative to the repo's versions.

Finale: CI

Our build tools in CI automatically update the docs inside the repo after a successful new build hits the master branch. This is accomplished by the GitHub action that calls pnpm changeset:version-with-docs which runs this script to rebuild docs and commit them into the repo (see sample commit here) as part of the final update PR.

TLDR: Local docs development

1. The one-time local setup for the custom plugin typedoc-plugin-guide-builder is to compile the Typescript, do

# start in root of project
cd ./scripts/typedoc-plugin-guide-builder
tsc

2. Next, you'll want to rebuild the generated typedoc files (see Part One above to understand why)

# start in root of project
pnpm typedoc

# if you plan to make a lot of updates, use `watch`
pnpm typedoc --watch

3. Finally, if you want to see how the docs will appear fully rendered as they do on the docs website, you will need to run Jekyll (see Part Two above to understand why). Setup Jekyll here if you haven't already.

# start in root of project
cd docs

# this will automatically `watch`, note that the initial build and "updates" can take several seconds/minutes
bundle exec jekyll serve