Update Composition Functions content to v1beta1 #583
Conversation
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Here's a rough draft of the topics I think I want to cover and where: In
In
In
I think each of these Functions could use some documentation somewhere:
I'm not sure whether that should be the Marketplace or the docs site (knowledge base)? |
negz
force-pushed
the
functional
branch
4 times, most recently
from
2708eea to
ca40c42
Compare
|
@plumbis I'm (mostly) able to generate a Hugo-compatible page of API documentation for the types Crossplane uses to communicate with functions. See crossplane/crossplane#4914. These types are pretty deep - the SDKs will abstract them away a bit - but they're probably worth having access to for advanced function developers. Would it make sense to include these somewhere under content? Any idea where? They're fairly coupled to a Crossplane release. |
|
Is this a different type of API doc than the Crossplane CRDs? |
|
@plumbis Yeah, these docs are generated from protobuf schemas rather than CRD OpenAPI schemas. So it’s a different tool doing the generation. (See crossplane/crossplane#4914.) |
There was a problem hiding this comment.
@plumbis @phisco this is ready for review. There's more documentation to be done, but I can handle it in separate PRs. Namely I want to:
- Add a language-specific guide for Go.
- Make sure we're good on the packages front once Rewrite packages content and split into Config and Provider chapters #566 is merged.
| Here's a brief example of a `FunctionIO`: | ||
| <!-- vale write-good.Passive = NO --> | ||
| Here's an example of a tiny, hello world function. This example is written in | ||
| Go. |
There was a problem hiding this comment.
@plumbis, Vale seems to be parsing "Go." (with period) as a word and complaining that it's a spelling mistake. Any idea how to fix that? I added Go (no period) to the dictionary.
|
|
||
| ### FunctionIO | ||
| See the [Crossplane CLI docs](https://github.com/crossplane/docs/pull/584) to |
There was a problem hiding this comment.
This link is a placeholder. Needs updating when #584 is merged.
| applying any changes to the API server. Crossplane surfaces this error as a | ||
| `Warning` event, a debug log, and by setting the `Synced` status condition of | ||
| the XR to "False". | ||
| You use the [Crossplane CLI](https://github.com/crossplane/docs/pull/584) to |
There was a problem hiding this comment.
This link is a placeholder. Needs updating when #584 is merged.
|
I haven't read very thoroughly, but this seem really nice to me! |
| <!-- vale write-good.Passive = NO --> | ||
| Here's an example of a tiny, hello world function. This example is written in | ||
| [Go](https://go.dev). | ||
| <!-- vale write-good.Passive = YES --> |
There was a problem hiding this comment.
| <!-- vale write-good.Passive = NO --> | |
| Here's an example of a tiny, hello world function. This example is written in | |
| [Go](https://go.dev). | |
| <!-- vale write-good.Passive = YES --> | |
| Here's an example of a tiny, hello world function. This example is in | |
| [Go](https://go.dev). |
This updates all current documentation of Composition Functions in the master directory to reflect the new v1beta1 implementation. Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
I plan to use the same page to document how to write a composition function. I'll add that documenation in a future commit. Signed-off-by: Nic Cope <[email protected]>
Per instructions from Hugo: https://gohugo.io/content-management/diagrams/#mermaid-diagrams The styling could probably be updated to be more in line with the rest of the docs, but this already looks better to me than the goat ASCII diagrams Hugo supports out of the box. Signed-off-by: Nic Cope <[email protected]>
This consists of two sections in the existing page: * How to write a function * How functions work The former is somewhat light, because I intend to add detailed guides for each language we support. It's hard to go too deep in this general documentation without using language-specific examples. Signed-off-by: Nic Cope <[email protected]>
Also sort -u the jargon file, because I'm too lazy to figure out ordering manually. :) Signed-off-by: Nic Cope <[email protected]>
We might want to update these to marketplace links once they're available. Signed-off-by: Nic Cope <[email protected]>
In particular, elaborate on how to test a function that is under development. Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
They no longer exist in v1.14 Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
Signed-off-by: Nic Cope <[email protected]> Co-authored-by: Pete Lumbis <[email protected]>
This could look better but it's a good start to make the diagrams match the light/dark theme. There is a bug in here that switching themes doesn't update the diagram (but it works on future loads) Signed-off-by: Nic Cope <[email protected]> Co-authored-by: Pete Lumbis <[email protected]>
Signed-off-by: Nic Cope <[email protected]>
Honestly mostly to workaround Vale thinking "Go." is a spelling mistake. Signed-off-by: Nic Cope <[email protected]>
Relates to #579
Relates to #582
This PR documents how to use composition functions. It also covers everything I think we need to cover about how they work and how to write them, short of language-specific guides. I plan to add a more detailed language-specific guide for Go that covers function-sdk-go and function-template-go in a separate PR.