Merge pull request #258 from disneystreaming/publish-docs

Publish docs

Author: lewisjkl

README.md

@@ -276,10 +276,7 @@ object traits extends BaseJavaModule with BasePublishModule {
   }
 
   object tests extends Cross[TestsModule](scalaVersions)
-  trait TestsModule
-      extends CrossScalaModule
-      with JavaModuleTests
-      with BaseMunitTests
+  trait TestsModule extends CrossScalaModule with JavaTests with BaseMunitTests
 }
 
 object `readme-validator` extends BaseScala213Module {
@@ -291,10 +288,8 @@ object `readme-validator` extends BaseScala213Module {
     buildDeps.lihaoyi.oslib
   )
 
-  def readmeFile = T.sources { os.pwd / "README.md" }
-
   def validate() = T.command {
-    val args = Seq(readmeFile().head.path.toString)
+    val args = docs.docFiles().map(_.path.toString)
     mill.util.Jvm.runSubprocess(
       finalMainClass(),
       runClasspath().map(_.path),
@@ -303,6 +298,19 @@ object `readme-validator` extends BaseScala213Module {
   }
 }
 
+object docs extends BasePublishModule {
+
+  override def publishArtifactName = "smithytranslate-docs"
+
+  def docFiles =
+    T.sources(os.walk(millSourcePath).map(mill.api.PathRef(_)))
+
+  override def resources = T.sources {
+    docFiles()
+  }
+
+}
+
 object proto extends Cross[ProtoModule](scalaVersions)
 trait ProtoModule
     extends CrossScalaModule

build.sc

@@ -0,0 +1,26 @@
+# Formatter
+
+### CLI Usage
+
+The `smithytranslate` CLI will recursively go through all child directories of the
+input directory provided and format any Smithy files it finds. The output
+
+```
+> smithytranslate format --help
+
+Usage: smithytranslate format [--no-clobber] <path to Smithy file or directory containing Smithy files>...
+
+validates and formats smithy files
+
+Options and flags:
+    --help
+        Display this help text.
+    --no-clobber
+        dont overwrite existing file instead create a new file with the word 'formatted' appended so test.smithy -> test_formatted.smithy
+```
+
+### Capabilities and Design
+ - The formatter is based off the ABNF defined at [Smithy-Idl-ABNF](https://smithy.io/2.0/spec/idl.html#smithy-idl-abnf)
+ - The formatter assumes the file is a valid Smithy file and must be able to pass the Model Assembler validation , otherwise it will return an error
+ - use --no-clobber to create a new file to avoid overwriting the original file
+ - actual formatting rules are still WIP and will be updated as the formatter is developed

modules/docs/formatter.md

@@ -0,0 +1,128 @@
+# JSON Schema
+
+### CLI Usage
+
+```
+> smithytranslate json-schema-to-smithy --help
+
+Usage: smithytranslate json-schema-to-smithy --input <path> [--input <path>]... [--verboseNames] [--failOnValidationErrors] [--useEnumTraitSyntax] [--outputJson] <directory>
+
+Take Json Schema specs as input and produce Smithy files as output.
+
+Options and flags:
+    --help
+        Display this help text.
+    --input <path>, -i <path>
+        input source files
+    --verbose-names
+        If set, names of shapes not be simplified and will be as verbose as possible
+    --validate-input
+        If set, abort the conversion if any input specs contains a validation error
+    --validate-output
+        If set, abort the conversion if any produced smithy spec contains a validation error
+    --enum-trait-syntax
+        output enum types with the smithy v1 enum trait (deprecated) syntax
+    --json-output
+        changes output format to be json representations of the smithy models
+```
+
+Run `smithytranslate json-schema-to-smithy --help` for all usage information.
+
+### Differences from OpenAPI
+
+Most of the functionality of the `OpenAPI => Smithy` conversion is the same for the `JSON Schema => Smithy` one. As such, here
+we will outline any differences that exist. Everything else is the same. See [OpenAPI docs](openapi.md) for more information.
+
+#### Default Values
+
+Default values from JSON Schema will be captured in the `smithy.api#default` trait.
+
+JSON Schema:
+```json
+{
+ "$id": "test.json",
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Person",
+ "type": "object",
+ "properties": {
+   "firstName": {
+     "type": "string",
+     "default": "Sally"
+   }
+ }
+}
+```
+
+Smithy:
+```smithy
+structure Person {
+ @default("Sally")
+ firstName: String
+}
+```
+
+#### Null Values
+
+JSON Schemas allows for declaring types such as `["string", "null"]`. This type declaration
+on a required field means that the value cannot be omitted from the `JSON` payload entirely,
+but may be set to `null`. For example:
+
+JSON Schema:
+```json
+{
+  "$id": "test.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Foo",
+  "type": "object",
+  "properties": {
+    "bar": {
+      "type": ["string", "null"]
+    }
+  },
+  "required": ["bar"]
+}
+```
+
+Smithy:
+```smithy
+use alloy#nullable
+
+structure Foo {
+ @required
+ @nullable
+ bar: String
+}
+```
+
+In most protocols, there is likely no difference between an optional field and a nullable optional field.
+Similarly, some protocols may not allow for required fields to be nullable. These considerations are left
+up to the protocol itself.
+
+#### Maps
+
+JSON Schema doesn't provide a first-class type for defining maps. As such, we translate a commonly-used
+convention into map types when encountered. When `patternProperties` is set to have a single entry, `.*`,
+we translate that to a smithy map type.
+
+JSON Schema:
+```json
+{
+  "$id": "test.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TestMap",
+  "type": "object",
+  "patternProperties": {
+    ".*": {
+      "type": "string"
+    }
+  }
+}
+```
+
+Smithy:
+```smithy
+map TestMap {
+ key: String,
+ value: String
+}
+```