create documentation microsite #56
Conversation
|
|
|
|
||
| - name: Compile Documentation Markdown Files | ||
| if: startsWith(github.ref, 'refs/tags/v') # do not run for snapshots | ||
| run: sbt "docs/mdoc" |
There was a problem hiding this comment.
Not positive this is needed here since we run it above in the CI steps. I am just not sure if the results will be cached along with the other compilation artifacts
There was a problem hiding this comment.
Seems worth checking, if we can avoid running sbt I'd give it a try :)
|
|
|
|
||
| - name: Compile Documentation Markdown Files | ||
| if: startsWith(github.ref, 'refs/tags/v') # do not run for snapshots | ||
| run: sbt "docs/mdoc" |
There was a problem hiding this comment.
Seems worth checking, if we can avoid running sbt I'd give it a try :)
modules/website/src/pages/index.js
Outdated
| <Link | ||
| className="button button--secondary button--lg" | ||
| to="/docs/intro"> | ||
| Get Started - 5min ⏱️ |
There was a problem hiding this comment.
lmao, I always thought this time estimation was generated 😂
|
It'd be sick if we could generate previews for changes in the microsite. Any chance we can integrate with Netlify in some github action? |
| description: ( | ||
| <> | ||
| Smithy4s will generate Scala code from your Smithy files. This means your servers | ||
| and clients will be generated from the same source of truth. |
There was a problem hiding this comment.
I'd add a newline and mention that the generated code contains precise metadata about the types, which allows building tooling on top of Smithy4s. Maybe with some examples of potential ideas like CLIs
@kubukoz I wouldn't mind it, preferably in a later unit of work. I'm currently revising (and making changes) to the docs content, so please do not touch the modules/docs folder if you're gonna touch this PR 😄 |
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
nit: lots of whitespace. Someone should enable trimming trailing newlines in their editors :D
|
|
||
| The code generated by smithy4s is strictly **protocol agnostic**, meaning that there is no particular processing to handle HTTP semantics, or JSON semantics in the generated code. | ||
|
|
||
| Instead, smithy4s relies on a number of highly polymorphic interfaces to communicate with the generated code, and derive JSON codecs out of it, or turn high level user provided code into HTTP services. But in theory, the same generated code can be used conjointly with other serialisation technologies (protobuf for instance) and protocols (gRPC). |
There was a problem hiding this comment.
nit: I feel like the word metadata should appear somewhere here
modules/docs/src/03-protocols/02-simple-rest-json/01-overview.md
Outdated
Show resolved
Hide resolved
|
|
||
| ## Semantics | ||
|
|
||
| In this protocol, the values in shapes are bound to http metadata or body according to the specification of the [Http Binding traits](https://awslabs.github.io/smithy/1.0/spec/core/http-traits.html?highlight=http#http-binding-traits). However, the `@mediaType` trait has no incidence, and all bodies (when present) are serialised in JSON. |
There was a problem hiding this comment.
should we mention jsoniter here?
|
preview at this point: https://61e860c575fc0167da5ae8ca--competent-tereshkova-bd73e4.netlify.app/ |
Co-authored-by: Jakub Kozłowski <jakub.kozlowski@disneystreaming.com>
modules/docs/src/03-protocols/02-simple-rest-json/01-overview.md
Outdated
Show resolved
Hide resolved
modules/docs/src/03-protocols/02-simple-rest-json/01-overview.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Jakub Kozłowski <jakub.kozlowski@disneystreaming.com>
Co-authored-by: Jakub Kozłowski <jakub.kozlowski@disneystreaming.com>
Adds a documentation microsite, and moves most contents of the readme over to the site Co-authored-by: Olivier Mélois <baccata64@gmail.com> Co-authored-by: Jakub Kozłowski <jakub.kozlowski@disneystreaming.com>
Moves the current README into a docs project with mdoc setup. From there adds a docusaurus microsite. Colors/copy/etc can all be changed of course, I just went with what made sense off the top of my head.
This will make it so the microsite is pushed to a new branch
gh-pages. We will need to set this branch to be the github pages page in the settings for this repo.