docs: Add multi-language entrypoint function page #7351

vikram-dagger · 2024-05-10T14:45:59Z

No description provided.

vikram-dagger · 2024-05-10T14:48:02Z

Noting that in this case, the original constructor pages for TypeScript and Python have been split, with the first common section extracted to a multi-language page and the remainder left as language-specific content. @helderco and @TomChv please review this to confirm nothing has been lost in translation.

kpenfound

This makes sense!

TomChv · 2024-05-14T00:11:55Z

Hey! Thanks for the changes I'm going to review this tomorrow! 👀

helderco · 2024-05-15T13:14:37Z

Note to use latest dagger version to update the output of --help since there's been some changes there. Flags, for example, have been renamed to Options, but specifically in the case of dagger call, they show as Arguments.

More context in:

De-clutter dagger call --help #6943

helderco · 2024-05-13T14:53:09Z

docs/current_docs/manuals/developer/constructor.mdx

+:::note
+If you plan to use constructor fields in other module functions, ensure that they are declared as public. This is because Dagger stores fields using JSON marshalling and private fields are omitted during the marshalling process. As a result, if a field is not declared as public, calling methods that use it will produce unexpected results.
+:::


"declared as public" isn't a thing in Python.

"Marshalling" is a term usually seen in Go. Can use the more general terms "serialization" and "deserialization" (no need for mentioning JSON too).

helderco · 2024-05-13T15:12:51Z

docs/current_docs/manuals/developer/python/constructor.mdx

+:::info
+This language-specific page should be read together with the main [module constructor documentation](../constructor.mdx).
+:::


I think this should evolve into one page per SDK for more details on various topics, including this one.

It's not necessaritly that this page needs to be read together with the common one if we can make the common section like a sort of basics, and the language-specific more like advanced/detailed information.

In that sense, I think it's ok to have some SDK specific information inside an SDK tab, if it helps to cover the "basics". Even better if we can use collapsed admonitions, like this:

Generally speaking, collapsed admonitions would help keep the content lighter, while still providing additional (and optional) information without having to link to another page in a lot of cases.

For the moment I have removed this note. I would like to separately discuss the topic of a single language-specific page vs a language category. Briefly, for me, the latter has two advantages:

avoids overloading too much content on one page (eg. this Python-specific constructor page already has a lot of information)

makes it more visible, as each language-specific page will have a separate sidebar entry

helderco · 2024-05-15T12:49:58Z

docs/current_docs/manuals/developer/constructor.mdx

+```
+
+:::note
+Dagger modules have only one constructor. Constructors of custom types are not registered; they are constructed by the function that [chains](./chaining.mdx) them.


Removed the link to custom types, I assume because that doc merge hasn't been merged yet. But it's already been approved so making a note to not forget adding it here.

helderco · 2024-05-15T12:55:55Z

docs/current_docs/manuals/developer/constructor.mdx

+
+The code listing above is an example of an object that has typed attributes.
+
+[Learn more about Python module constructors](./python/constructor.mdx).


This link looks a bit off in the middle of the text here:

Could use a visual break, if not a section break (no one that makes sense here) maybe an arrow/emoji, or in an admnonition.

Moved to end of page

helderco · 2024-05-15T12:57:23Z

docs/current_docs/manuals/developer/constructor.mdx

+```python file=./snippets/constructor/python/main.py
+```
+
+In the Python SDK, the [`@dagger.object_type`](https://dagger-io.readthedocs.io/en/latest/module.html#dagger.object_type) decorator wraps [`@dataclasses.dataclass`](https://docs.python.org/3/library/dataclasses.html), which means that an `__init__()` method is automatically generated, with parameters that match the declared class attributes.


I think this would be better in an info admonition. It's important to know that @object_type is a @dataclass. Perhaps even put the "learn more" link here as most of that is about the dataclass thing.

Changed to admonition. Link is added at the end of the page

docs/current_docs/manuals/developer/python/constructor.mdx

helderco · 2024-05-15T13:18:59Z

docs/current_docs/manuals/developer/python/constructor.mdx

In "Asynchronous constructor", maybe embolden:

a factory class method which must be named create:

It's important to know it has to have that name.

Changed to highlight box

vikram-dagger · 2024-05-16T10:40:54Z

Note to use latest dagger version to update the output of --help since there's been some changes there.

Updated. Can you please review again @helderco ? Thank you!

levlaz · 2024-05-24T20:24:12Z

Vikram and I looked this, once links are removed and bottom note is combined I think this is ready to ship.

vikram-dagger · 2024-05-25T07:17:00Z

Noting here that the language-specific constructor pages have very different examples. These have been merged into this page under separate headings. I'm not sure if these are different because of actual disparity between SDKs or because they were authored at different times. See the preview at https://deploy-preview-7351--devel-docs-dagger-io.netlify.app/manuals/developer/constructor/

I would like @helderco @TomChv @kpenfound to review this once and advise which of the language-specific examples could be made multi-language. I'm not sure if we need to block merging this PR until the above is reviewed and new examples possibly created by the SDK maintainers. WDYT @helderco @levlaz @jpadams @kpenfound ?

shykes · 2024-05-25T07:38:23Z

Can I also request that we call this topic "entrypoint functions" and explain that every module has one. The default one is generated automatically and has no arguments; It's possible to write a custom entrypoint function, the mechanism is SDK-specific.

vikram-dagger · 2024-05-25T07:55:54Z

Can I also request that we call this topic "entrypoint functions" and explain that every module has one. The default one is generated automatically and has no arguments; It's possible to write a custom entrypoint function, the mechanism is SDK-specific.

Done, let me know if further changes needed. I made this change in the title, intro and first section but not in the following language-specific ones since the constructor mechanism has been explained by that point.

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

This reverts commit dff4791. Signed-off-by: Vikram Vaswani <vikram@dagger.io>

This reverts commit 2f27465. Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger · 2024-05-25T08:04:41Z

docs/current_docs/manuals/developer/python/428321-constructor.mdx

-Hello, Daggerverse!
-```
-
-Constructor arguments are documented through their attribute documentation,


This inline doc section is not transferred because there is a similar example (object documentation) already provided in the inline documentation page, but lmk if this is not correct @helderco

TomChv

I left small comments about the organization of this page.

TomChv · 2024-05-27T22:53:09Z

docs/current_docs/manuals/developer/entrypoint-function.mdx

+If you plan to use constructor fields in other module functions, ensure that they are declared as public (in Go and TypeScript). This is because Dagger stores fields using serialization and private fields are omitted during the serialization process. As a result, if a field is not declared as public, calling methods that use it will produce unexpected results.
+:::
+
+## Exclude argument in constructor (Python)


Is there a way to put this in a specific Python tab? It looks strange to read that if I'm on the TS or Go doc.

And I could miss some details, for example TypeScript specificity is at the bottom so users could miss it.

Yes, I can try. Can you please let me know if any of the Python examples can be replicated in TypeScript? If yes, can you add the code snippets?

You should be able to do it but just setting default arg in the field and not adding it in the constructor

TomChv · 2024-05-27T22:53:40Z

docs/current_docs/manuals/developer/entrypoint-function.mdx

+```
+
+:::note
+If you plan to use constructor fields in other module functions, ensure that they are declared as public (in Go and TypeScript). This is because Dagger stores fields using serialization and private fields are omitted during the serialization process. As a result, if a field is not declared as public, calling methods that use it will produce unexpected results.


I understand that we're multi language but here you mention Go, we should have a specific Go section instead?

mircubed · 2024-05-31T19:32:14Z

Next steps as of 5/31 - @TomChv please take the lead to make decision for this specific comment, so we can move forward with next steps on this PR since Helder is OOO next week.

TomChv · 2024-06-03T16:37:01Z

docs/current_docs/manuals/developer/entrypoint-function.mdx

+The information in this section is only applicable to the Python SDK.
+:::
+
+The opposite is also possible. To define an argument that only exists in


You could do it by not exposing the @field inside a variable, this should works

TomChv · 2024-06-03T16:37:27Z

docs/current_docs/manuals/developer/entrypoint-function.mdx

+```python file=./snippets/entrypoint/python/factory/main.py
+```
+
+## Asynchronous constructor (Python)


Not possible in Typescript without a hack that we don't want to recommand

TomChv · 2024-06-03T16:37:59Z

docs/current_docs/manuals/developer/entrypoint-function.mdx

+```python file=./snippets/entrypoint/python/initvar/main.py
+```
+
+## Complex or mutable defaults (Python)


You can call new to constructor a complex object or dag.xxx for a dagger object inside the constructor

mircubed · 2024-06-03T19:41:58Z

Next steps: @vikram-dagger will take the next steps on this PR.

expand complex types
Will clean up the Python-specific things into a Python tab. The other language tabs will be left blank as discussed with @marcosnils

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger · 2024-06-04T15:07:59Z

Next steps: @vikram-dagger will take the next steps on this PR.

expand complex types

Done

Will clean up the Python-specific things into a Python tab. The other language tabs will be left blank as discussed with @marcosnils

Done, except that instead of tabs I'm leaving these as sections with a note that these are only applicable to Python (this is the format already used in other pages)

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

docs/current_docs/manuals/developer/snippets/entrypoint/go/default-object/main.go

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger · 2024-06-04T15:27:08Z

docs/current_docs/manuals/developer/snippets/entrypoint/go/default-object/main.go

+import "context"
+
+func New(
+	// +default=dag.Container().From("alpine:3.14.0")


Error

Error: generate code: template: alias.go.tmpl:76:3: executing "_dagger.gen.go/alias.go.tmpl" at <ModuleMainSrc>: error calling ModuleMainSrc: failed to generate type def code for MyModule: failed to convert constructor to function def: default value "dag.Container().From(\"alpine:3.14.0\")" must be valid JSON: invalid character 'd' looking for beginning of value

I don't think this is possible? In go you can just have it as +optional and then in the constructor say

if ctr == nil { ctr = dag.Container().From("alpine:3.14.0") }

Updated and ready for review

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger requested review from helderco, TomChv and kpenfound May 10, 2024 14:46

vikram-dagger force-pushed the docs-243-constructor branch from 51c593d to d043e1a Compare May 10, 2024 14:48

kpenfound approved these changes May 10, 2024

View reviewed changes

vikram-dagger force-pushed the docs-243-constructor branch 2 times, most recently from fffc5ca to 8ff0552 Compare May 14, 2024 13:50

helderco reviewed May 15, 2024

View reviewed changes

vikram-dagger force-pushed the docs-243-constructor branch from 8ff0552 to e4f156f Compare May 16, 2024 09:23

vikram-dagger force-pushed the docs-243-constructor branch 2 times, most recently from 856fc66 to 71131e8 Compare May 25, 2024 06:52

vikram-dagger requested review from helderco, kpenfound, shykes, marcosnils and levlaz May 25, 2024 07:51

vikram-dagger added 6 commits May 25, 2024 13:29

Add multi-language constructor page

eac87cd

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Revert "Add multi-language constructor page"

9532de9

This reverts commit dff4791. Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Revert "Revert "Add multi-language constructor page""

4a82ccf

This reverts commit 2f27465. Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Added cross-links

38038c8

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Fixed links

7c518e7

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Add feedback

551332d

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger added 3 commits May 25, 2024 13:30

Update page title and related

4c5a93b

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Remove blank line

70c9626

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Fix links

672a0cb

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger force-pushed the docs-243-constructor branch from b07d815 to 672a0cb Compare May 25, 2024 08:02

vikram-dagger commented May 25, 2024

View reviewed changes

vikram-dagger changed the title ~~docs: Add multi-language constructor page~~ docs: Add multi-language entrypoint function page May 25, 2024

TomChv reviewed May 27, 2024

View reviewed changes

vikram-dagger marked this pull request as draft May 28, 2024 07:46

mircubed removed request for shykes, helderco, marcosnils, kpenfound and levlaz May 31, 2024 19:22

TomChv reviewed Jun 3, 2024

View reviewed changes

Updated snippets

888195f

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Fixed code

79e96a1

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger commented Jun 4, 2024

View reviewed changes

docs/current_docs/manuals/developer/snippets/entrypoint/go/default-object/main.go Outdated Show resolved Hide resolved

Update code

e287f78

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger commented Jun 4, 2024

View reviewed changes

Fix lint

8c13e35

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger marked this pull request as ready for review June 4, 2024 15:30

mircubed added the area/documentation Improvements or additions to documentation label Jun 4, 2024

vikram-dagger added 2 commits June 5, 2024 01:25

Fix link

b4e6d65

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

Updated Go example

04182ea

Signed-off-by: Vikram Vaswani <vikram@dagger.io>

vikram-dagger merged commit 8a01e3f into dagger:main Jun 4, 2024
57 of 58 checks passed


		The code listing above is an example of an object that has typed attributes.

		[Learn more about Python module constructors](./python/constructor.mdx).

docs: Add multi-language entrypoint function page #7351

docs: Add multi-language entrypoint function page #7351

Conversation

vikram-dagger commented May 10, 2024

vikram-dagger commented May 10, 2024

kpenfound left a comment

Choose a reason for hiding this comment

TomChv commented May 14, 2024

helderco commented May 15, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vikram-dagger commented May 16, 2024

levlaz commented May 24, 2024

vikram-dagger commented May 25, 2024 • edited

shykes commented May 25, 2024

vikram-dagger commented May 25, 2024

Choose a reason for hiding this comment

TomChv left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mircubed commented May 31, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mircubed commented Jun 3, 2024

vikram-dagger commented Jun 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vikram-dagger commented May 25, 2024 •

edited