golemcloud / docs Goto Github PK

Need to investigate why this happens, maybe move away from lefthook in favor of something else

complete console docs section

Original Nextra Layout

{
 "cli": {
    "title": "CLI"
  },
  "-- Console": {
    "type": "separator",
    "title": "Console"
  },
  "-- Troubleshooting": {
    "type": "separator",
    "title": "Troubleshooting"
  },
  "-- References": {
    "type": "separator",
    "title": "References"
  },
}

complete troubleshooting docs section

Original Nextra Layout

{
 "cli": {
    "title": "CLI"
  },
  "-- Console": {
    "type": "separator",
    "title": "Console"
  },
  "-- Troubleshooting": {
    "type": "separator",
    "title": "Troubleshooting"
  },
  "-- References": {
    "type": "separator",
    "title": "References"
  },
}

Currently we have the following documentation for supported guest languages:

"Building components"
=>  "Tier N"
=> => "Language"

For each the structure currently is basically:

• Required tools
• Very small mention of ability to use golem-cli new
• Detailed description of how to do everything by hand from zero
• For Rust there is a mention of golem-rust
• For Rust and Go there is a section of how to do HTTP
• For JS and TS there is a small section about how to use additional WIT dependencies but not much details

I propose the following changes:

• Structure the page so that people arrive immediately to the list of Tier 1 languages, and keep the other few supported ones in somewhere deeper in the tree
• For each Tier 1 language, have the following sections:
  • Prerequisites (what to install and how) - should be prepared to have docs for more than just OSX
  • Quickstart with golem-cli with a concrete example from 0 to having the WASM (we should have a default 'getting started' example in golem-examples for each tier 1 language)
  • Section about how to export interfaces, custom data types and resources (whether requires editing WIT and where to put it, and how it looks in code)
  • Section about importing interfaces
  • Section about using HTTP (in Rust and Go it should only mention the reqwest/go libraries)
  • Section about using the transaction API (in Rust refer to the golem-rust lib, for others now just build on the previous sections on how to import it - explanation of the API is on the separate top level page)
• In other top level pages (Worker to Worker communication, Transactions, Promises) make sure to:
  • They describe the general concept and usability in a language-independent way
  • They link to the appropriate parts of the restructured guest language pages to learn how to use them in each language
  • There should be a golem-cli new ... example for each of these for each supported language that provides a good starting point and example people can look at
  • Maybe we could have per-language sub pages highlighting parts of these examples so it is also browsable as part of the webpage and not just if you generate it for yourself

REST API Pages are auto-generated from OpenAPI spec

The command to re-generate the pages

From Dev spec

https://release.dev-api.golem.cloud/specs

bun run generateDev

From Prod spec

https://release.api.golem.cloud/specs

bun run generateProd

The generation script is likely out of date after #44 gets merged since the page layout changed. so it will require some debugging to update

So, the golem docs mention that you need version 15+, then say "just use brew."

For those of us who aren't on Mac, we're sent to the protoc website, which has a helpful script to install it.

Unfortunately, it grabs version 3.14.

So, having a look at those scripts, then modifying them to grab a newer version, and having them in the docs would be enormously helpful.

The new endpoint and host function must be added to learn.golem.cloud.