docs: Add multi-language entrypoint function page #7351
Conversation
|
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. |
vikram-dagger
force-pushed
the
docs-243-constructor
branch
from
51c593d
to
d043e1a
Compare
|
Hey! Thanks for the changes I'm going to review this tomorrow! 👀 |
vikram-dagger
force-pushed
the
docs-243-constructor
branch
2 times, most recently
from
fffc5ca
to
8ff0552
Compare
|
Note to use latest dagger version to update the output of More context in: |
| :::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. | ||
| ::: |
There was a problem hiding this comment.
"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).
| :::info | ||
| This language-specific page should be read together with the main [module constructor documentation](../constructor.mdx). | ||
| ::: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
| ``` | ||
|
|
||
| :::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. |
There was a problem hiding this comment.
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.
|
|
||
| The code listing above is an example of an object that has typed attributes. | ||
|
|
||
| [Learn more about Python module constructors](./python/constructor.mdx). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Moved to end of page
| ```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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Changed to admonition. Link is added at the end of the page
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Changed to highlight box
vikram-dagger
force-pushed
the
docs-243-constructor
branch
from
8ff0552
to
e4f156f
Compare
Updated. Can you please review again @helderco ? Thank you! |
|
Vikram and I looked this, once links are removed and bottom note is combined I think this is ready to ship. |
vikram-dagger
force-pushed
the
docs-243-constructor
branch
2 times, most recently
from
856fc66
to
71131e8
Compare
|
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 ? |
|
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
requested review from
helderco,
kpenfound,
shykes,
marcosnils and
levlaz
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 |
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>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
Signed-off-by: Vikram Vaswani <vikram@dagger.io>
vikram-dagger
force-pushed
the
docs-243-constructor
branch
from
b07d815
to
672a0cb
Compare
| Hello, Daggerverse! | ||
| ``` | ||
|
|
||
| Constructor arguments are documented through their attribute documentation, |
There was a problem hiding this comment.
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
vikram-dagger
changed the title
No description provided.