docs: Create language-specific pages

docs/current_docs/manuals/developer/go/637319-interfaces.mdx → docs/current_docs/manuals/developer/go.mdx

@@ -1,13 +1,15 @@
 ---
-slug: /manuals/developer/go/637319/interfaces
+slug: /manuals/developer/go
 displayed_sidebar: "current"
 toc_max_heading_level: 2
-title: "Interfaces"
+title: "Go Extras"
 ---
 
+# Go Extras
 
-# Interfaces
+This page lists features specific to the Go SDK.
 
+## Interfaces
 
 The Go SDK supports interfaces, which allow you to define Go-style interface
 definitions so that your module can accept arbitrary values from other modules
@@ -16,7 +18,7 @@ without being tightly coupled to the concrete type underneath.
 To use an interface, define a Go interface that embeds `DaggerObject` and use
 it in a function argument:
 
-```go file=./snippets/interfaces/main.go
+```go file=./snippets/go/interfaces/main.go
 ```
 
 Functions defined in interface definitions must match the client-side API

docs/current_docs/manuals/developer/python.mdx

@@ -0,0 +1,98 @@
+---
+slug: /manuals/developer/python
+displayed_sidebar: "current"
+toc_max_heading_level: 2
+title: "Python Extras"
+---
+
+# Python Extras
+
+This page lists features specific to the Python SDK.
+
+## Name overrides
+
+Sometimes it's possible to get into a situation where the name you want to use
+for the Dagger API is reserved or has a naming conflict within Python.
+
+To resolve this, the [`@dagger.function`][@function] decorator and the
+[`dagger.field`][dag-field] descriptor have a `name` argument to provide
+an alternative name for the Dagger API. And for function arguments,
+[annotate][Annotated] with an additional [`dagger.Arg`][dag-arg] metadata.
+
+Here's an example with a renamed object attribute (and constructor argument),
+function and function argument:
+
+```python file=./snippets/python/name-overrides/main.py
+```
+
+Confirm with `dagger call --help` that the names were overridden:
+
+```
+FUNCTIONS
+  def           Definition
+  import        Import the specified image
+
+ARGUMENTS
+      --def string   Definition (default "latest")
+```
+
+And the same for the function argument, with `dagger call import --help`:
+
+```
+ARGUMENTS
+      --from string   Image ref (default "alpine")
+```
+
+[@function]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.function
+[dag-field]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.field
+[dag-arg]: https://dagger-io.readthedocs.io/en/latest/module.html#dagger.Arg
+[Annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated
+
+## Python debug logs
+
+The Python SDK prints debugging information at various steps of the execution
+flow of a module, which can be very useful in understanding what's being
+received from and sent to the API.
+
+This is done using standard Python [logging](https://docs.python.org/3/howto/logging.html),
+so it's highly configurable (for example, saving to a file or sending to an
+external system like Sentry). But for a simple lowering of the default logging
+level to [logging.DEBUG](https://docs.python.org/3/library/logging.html#logging.DEBUG),
+there's a convenience function for that:
+
+```python file=./snippets/python/debugging/main.py
+```
+
+:::note
+With the TUI, you need to use a progress output that doesn't collapse on success
+like `--progress=plain` or `--debug`, otherwise it won't show in the terminal.
+:::
+
+Using the command `dagger call --debug echo --msg="hello"`, should print
+something like:
+
+```
+✔ MyModule.echo(msg: "hello"): String! 0.5s
+  ✔ exec /runtime 0.5s
+  ┃ [DEBUG] dagger.client._session: Configuring shared connection to GraphQL server
+  ┃ [DEBUG] dagger.client._session: Establishing client session to GraphQL server
+  ┃ [DEBUG] dagger.mod._module: invoke => {'parent_name': 'MyModule', 'parent_json': '{}', 'name': 'echo', 'input_args': "{'msg': 'hello'}"}
+  ┃ [DEBUG] dagger.mod._module: resolver => MyModule.echo
+  ┃ [DEBUG] dagger.mod._resolver: func => <Signature (msg: str) -> str>
+  ┃ [DEBUG] dagger.mod._resolver: input args => {'msg': 'hello'}
+  ┃ [DEBUG] dagger.mod._resolver: structured args => {'msg': 'hello'}
+  ┃ [DEBUG] dagger.mod._module: result => 'hello'
+  ┃ [DEBUG] dagger.mod._module: output => '"hello"'
+  ┃ [DEBUG] dagger.client._session: Closing client session to GraphQL server
+DEBUG: executing query="query{myModule{echo(msg:\"hello\")}}"
+```
+
+The above gives a lot of useful information:
+- The function and parent object that the API wants to execute
+- The parent object's state
+- The function's signature
+- The user inputs before and after deserialization
+- The user inputs after being converted to more complex types (structuring)
+- The function's result before and after serialization
+
+Additionally, with `--debug`, the GraphQL query that the Dagger CLI produced is also shown.

docs/current_docs/manuals/developer/typescript/356352-runtime.mdx → docs/current_docs/manuals/developer/typescript.mdx

@@ -1,11 +1,15 @@
 ---
-slug: /manuals/developer/typescript/356352/runtime
+slug: /manuals/developer/typescript
 displayed_sidebar: "current"
 toc_max_heading_level: 2
-title: "Runtimes"
+title: "TypeScript Extras"
 ---
 
-# Runtimes
+# TypeScript Extras
+
+This page lists features specific to the TypeScript SDK.
+
+## Runtimes
 
 TypeScript is supported by multiple runtimes: [Node.js](https://nodejs.org/en) (via tsx), [Deno](https://deno.com/) (natively) and [Bun](https://bun.sh/) (natively).
 
@@ -17,7 +21,7 @@ For now, the TypeScript SDK only supports Node.js (stable) and Bun (experimental
 
 To change the TypeScript SDK runtime, set the field `dagger.runtime` in the `package.json` file.
 
-## Node  
+### Node.js
 
 Set the field to `node` to use the Node.js runtime. Node.js is also the default runtime used if this field is omitted.
 
@@ -27,7 +31,7 @@ Set the field to `node` to use the Node.js runtime. Node.js is also the default
   }
 ```
 
-## Bun 
+### Bun
 
 Set the field to `bun` to use the Bun runtime.
 
@@ -40,7 +44,9 @@ Set the field to `bun` to use the Bun runtime.
 :::warning
 Bun runtime support is still experimental. Unexpected results may occur in some cases.
 :::
-## Automatic Detection
+
+### Automatic detection
+
 When a runtime is not explicitly defined within the `package.json` file, Dagger automatically identifies the appropriate runtime by examining the project's lock files inside the project's `dagger` directory.
 
 - If Dagger finds any of the following lock files : `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`, it automatically selects `node` as the runtime.
@@ -50,4 +56,22 @@ When a runtime is not explicitly defined within the `package.json` file, Dagger
 
 :::warning
 This behavior however should be seen as a sensible fallback and not as an explicit configuration.
-:::
+:::
+
+## Name overrides
+
+You can change the name of an exposed field or function to work around a reserved keyword or some other naming conflict, but still be able to expose the desired name in the Dagger API. For example, using `import_` in the language, but `import` in the Dagger API. To do so, simply add the alias as a parameter of the corresponding decorator.
+
+Here is an example of a module with the field `ctr` aliased as `container` and the function `displayVersion` aliased as `version`:
+
+```typescript file=./snippets/typescript/name-overrides/index.ts
+```
+
+Field and function names are overridden by their aliases in the output of `dagger functions`:
+
+```shell
+dagger functions
+Name        Description
+container   -
+version     -
+```

docs/netlify.toml

@@ -74,6 +74,30 @@
   to = "/manuals/developer/custom-types"
   status = 301
 
+[[redirects]]
+  # redirect developer manual TypeScript-specific pages to TypeScript common page
+  from = "/manuals/developer/typescript/:docid/runtime"
+  to = "/manuals/developer/typescript"
+  status = 301
+
+[[redirects]]
+  # redirect developer manual TypeScript-specific pages to TypeScript common page
+  from = "/manuals/developer/typescript/:docid/aliases"
+  to = "/manuals/developer/typescript"
+  status = 301
+
+[[redirects]]
+  # redirect developer manual Go-specific pages to Go common page
+  from = "/manuals/developer/go/:docid/interfaces"
+  to = "/manuals/developer/go"
+  status = 301
+
+[[redirects]]
+  # redirect developer manual Python-specific pages to Python common page
+  from = "/manuals/developer/python/:docid/name-overrides"
+  to = "/manuals/developer/python"
+  status = 301
+
 [[redirects]]
   # redirect developer manual overview pages
   from = "/manuals/developer/overview/:docid/*"

docs/sidebars.ts

@@ -340,6 +340,18 @@ module.exports = {
           "type": "doc",
           "id": "manuals/developer/error-handling"
         },
+        {
+          "type": "doc",
+          "id": "manuals/developer/go"
+        },
+        {
+          "type": "doc",
+          "id": "manuals/developer/python"
+        },
+        {
+          "type": "doc",
+          "id": "manuals/developer/typescript"
+        },
         {
           "type": "category",
           "label": "Develop with Go",
@@ -360,10 +372,6 @@ module.exports = {
               "type": "doc",
               "id": "manuals/developer/go/constructor"
             },
-            {
-              "type": "doc",
-              "id": "manuals/developer/go/interfaces"
-            },
             {
               "type": "doc",
               "id": "manuals/developer/go/visibility"
@@ -415,10 +423,6 @@ module.exports = {
               "type": "doc",
               "id": "manuals/developer/python/name-overrides"
             },
-            {
-              "type": "doc",
-              "id": "manuals/developer/python/module-structure"
-            },
             {
               "type": "doc",
               "id": "manuals/developer/python/python-dependencies"
@@ -462,10 +466,6 @@ module.exports = {
               "type": "doc",
               "id": "manuals/developer/typescript/decorators"
             },
-            {
-              "type": "doc",
-              "id": "manuals/developer/typescript/aliases"
-            },
             {
               "type": "doc",
               "id": "manuals/developer/typescript/visibility"
@@ -486,10 +486,6 @@ module.exports = {
               "type": "doc",
               "id": "manuals/developer/typescript/debugging"
             },
-            {
-              "type": "doc",
-              "id": "manuals/developer/typescript/runtime"
-            },
             {
               "type": "doc",
               "label": "Reference",