Switching docs over to docsify

guardrail-dev · Dec 17, 2023 · b08f5af · b08f5af
1 parent 2a7400d
commit b08f5af
Show file tree

Hide file tree

Showing 95 changed files with 2,665 additions and 1,287 deletions.
diff --git a/.github/workflows/publish-website.yml b/.github/workflows/publish-website.yml
@@ -11,23 +11,25 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: actions/setup-java@v4
+      - uses: olafurpg/setup-scala@v14
         with:
-          distribution: zulu
-          java-version: 14
-      - uses: ruby/[email protected]
-        with:
-          bundler-cache: true
-      - name: Install microsite deps
-        run: |
-          bundle install --jobs 4 --retry 3 --system
+          java-version: [email protected]
       - name: Print versions
         run: |
           java -version
-          gpg --version
-          ruby --version
-          bundle exec jekyll --version
       - name: Update website
         env:
           MICROSITE_PUBLISH_TOKEN: ${{ secrets.MICROSITE_PUBLISH_TOKEN }}
-        run: bundle exec sbt microsite/makeMicrosite microsite/publishMicrosite
+        run: |
+          git clone "https://git:[email protected]/guardrail-dev/guardrail.git" --branch=gh-pages gh-pages && \
+            pushd gh-pages && \
+            git rm -rf . && \
+            git config user.email "[email protected]" && \
+            git config user.name "guardrail website builder" && \
+            popd && \
+            sbt microsite/mdoc && \
+            tar -cC modules/microsite/target/mdoc/ . | tar -vxC gh-pages && \
+            pushd gh-pages && \
+            git add . && \
+            git commit -m "Updating ${{ github.ref_name }}" && \
+            git push
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ vendor/
 .bundle/
 metals.sbt
 .sbtopts
+node_modules/
diff --git a/Gemfile b/Gemfile
diff --git a/Gemfile.lock b/Gemfile.lock
diff --git a/build.sbt b/build.sbt
@@ -182,6 +182,7 @@ lazy val scalaDropwizard = modules.scalaDropwizard.project
   .customDependsOn("scala-support", scalaSupport)
 
 lazy val microsite = baseModule("microsite", "microsite", file("modules/microsite"))
+  .enablePlugins(MdocPlugin)
   .settings(
     publish / skip := true,
     mdocExtraArguments += "--no-link-hygiene",

diff --git a/modules/microsite/docs/docs/scalajs/index.md → docs/.nojekyll b/modules/microsite/docs/docs/scalajs/index.md → docs/.nojekyll
diff --git a/modules/microsite/docs/CNAME → docs/CNAME b/modules/microsite/docs/CNAME → docs/CNAME
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,27 @@
+Introduction
+===
+
+[![Build Status](https://github.com/guardrail-dev/guardrail/workflows/CI/badge.svg)](https://github.com/guardrail-dev/guardrail/actions?query=workflow%3A%22CI%22) | [![codecov](https://codecov.io/gh/guardrail-dev/guardrail/branch/master/graph/badge.svg?token=ssLYYkVBgv)](https://codecov.io/gh/guardrail-dev/guardrail) | [![Matrix chat](https://img.shields.io/matrix/guardrail:matrix.org.svg?label=matrix&server_fqdn=matrix.org)](https://matrix.to/#/#guardrail:matrix.org) | [![Join the chat at https://gitter.im/guardrail-dev/guardrail](https://badges.gitter.im/guardrail-dev/guardrail.svg)](https://gitter.im/guardrail-dev/guardrail?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) | [![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)
+
+[`guardrail`](https://github.com/guardrail-dev/guardrail) is a code generation tool, capable of reading from OpenAPI/Swagger specification files and generating high quality source code for a variety of languages and frameworks.
+
+Getting started
+===
+
+The following build tool plugins are available:
+
+- [`sbt-guardrail`](https://github.com/guardrail-dev/sbt-guardrail)
+- [`guardrail-maven-plugin`](https://github.com/guardrail-dev/guardrail-maven-plugin)
+- [`guardrail-gradle-plugin`](https://github.com/guardrail-dev/guardrail-gradle-plugin)
+- as well as a manual CLI runner available via [coursier](cli.md)
+
+New plugins are straightforward, simply call one of the exposed functions from
+[`GuardrailRunner`](https://github.com/guardrail-dev/guardrail/blob/master/modules/core/src/main/scala/dev/guardrail/runner/GuardrailRunner.scala)
+with appropriate arguments in order to get a sequence of generated files.
+
+**NB:** Ensure either you or your build tool deduplicates the file sequence, as
+they are not guaranteed to be unique across multiple runs of the guardrail core.
+
+Additionally, check out the [`guardrail-sample`](https://github.com/topics/guardrail-sample) topic on GitHub for more examples.
+
+**Consulting**: If you need help getting started, getting migrated, or adding features, please contact [[email protected]](mailto:[email protected]).
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,6 @@
+- [Home](/)
+- [What is guardrail?](about.md)
+- [Sample API Specification](sample-spec.md)
+- [Scala](scala/README.md)
+- [Java](java/README.md)
+- [Extensions](extensions.md)
diff --git a/...cs/docs/scala/http4s/what-is-guardrail.md → docs/about.md b/...cs/docs/scala/http4s/what-is-guardrail.md → docs/about.md
@@ -1,12 +1,7 @@
----
-layout: docs
-title: "What is guardrail? - http4s - scala - guardrail"
----
-
 What is guardrail?
 ==================
 
-guardrail is a code generation tool, capable of reading from OpenAPI/Swagger specification files and generating Scala source code, primarily targeting the akka-http and http4s web frameworks, using circe for JSON encoding/decoding.
+guardrail is a code generation tool, capable of reading from OpenAPI/Swagger specification files and generating source code in different languages with a focus on type safety and ergonomics in each target language.
 
 guardrail has three primary goals:
 
@@ -21,28 +16,42 @@ Single Point of Truth
 
 By describing the shape of an API statically, there are far fewer variables to worry about. HTTP is a _very_ flexible protocol, with many features. By constraining that protocol to a subset that expresses the interface to our server (or service, or microservice), we drastically reduce the burden of handling the entirety of HTTP to the core terms of our API. Focus on semantics of APIs once the basics (routing, data validation) are figured out.
 
-A secondary benefit of static specifications lies in tooling. Hand-written routing logic can hide security holes, miss best practices, and obscure intent if written incorrectly. This problem is multipled across as many different languages as are supported inside any given company, manifesting as wasted effort implementing the same feature in different languages, or a bug that only occurs 10 percent of the time due to a buggy golang client.
+A secondary benefit of static specifications lies in tooling. Hand-written routing logic can hide security holes, miss best practices, and obscure intent if written incorrectly. This problem is multipled across as many different languages as are supported inside any given company, manifesting as wasted effort implementing the same feature in different languages, or a bug that only occurs 10 percent of the time due to a buggy hand-written client.
 
 Attempting to derive what the attack surface of a server is from the implementation is often the job of entire teams in large companies, and even that may not be enough. Conversely, with a static specification, those teams can build intelligent traffic analysis tools to detect anomalies or intentionally malicious clients built to inject bad data to find bugs.
 
 Unexpected API changes are compiler errors
 ------------------------------------------
 
-Once we have a specification, generating traits (or abstract classes) with unimplemented members gives us another powerful tool: New or changed parameters become compiler errors.
+Once we have a specification, generating traits (or abstract classes) with unimplemented members gives us another powerful tool: New or changed parameters become compiler (or linting) errors.
+
+After constraining our vocabulary to a subset of HTTP that serves our business need, even saying "This parameter is optional" forces us to contend with the appearance of optional parameters in our generated `Handler` methods.
+
+Once specified, turning on "unused" warnings helpfully points out that we've forgotten to reflect this most recent change in our tests. A win on both fronts!
+
+Separation of business logic
+----------------------------
+
+Providing an implementation of a function with a well-defined set of inputs and outputs is natural for any developer. By reducing the scope of the interface a developer writes against, implementations are more clear and concise.
 
-After constraining our vocabulary to a subset of HTTP that serves our business need, even saying "This parameter is optional" forces us to contend with the sudden appearance of `Option[T]` parameters in our generated `Handler` methods.
+Furthermore, by providing business logic as an implementation of an abstract class, unit tests can test the routing layer and business logic independently, by design.
 
-Once specified, `-Ywarn-unused` helpfully points out that we've forgotten to reflect this most recent change in our tests. A win on both fronts!
+API structure slip is impossible
+--------------------------------
+
+As parameters are explicitly provided as arguments to functions in `Handler`s, any alteration to parameters constitute a new function interface that must be implemented. As a result, if providing an implementation for an externally managed specification, the compiler informs when a previously written function is no longer sufficient.
+
+By representing different response codes and structures as members of an enumeration of valid choices, it's impossible to return a structure that violates the specification, even for less frequently used responses.
+
+Finally, describing an endpoint in your specification without providing an implementation for it is an error. This prevents reduction of functionality due to refactors, human error, or miscommunication with other teams.
 
 Fewer binary dependencies
 ----------------------
 
-Traditionally written and maintained client libraries invariably accumulate cruft. In many cases, this is intended to be helpful: papering over a poorly designed API by providing custom logic, renaming parameters to be more convenient, or including properly configured HTTP clients that express retry and backoff semantics the library author provided based on the business requirements known at the time of writing.
+Bespoke, hand-written and maintained client libraries invariably accumulate cruft. In many cases, this is intended to be helpful: papering over a poorly designed API by providing custom logic, renaming parameters to be more convenient, or including properly configured HTTP clients that express retry and backoff semantics the library author provided based on the business requirements known at the time of writing.
 
-Altering the shape of an API by providing a thick HTTP client reduces the shared terminology between service maintainers and their consumers, or even between consumers coming from different languages.
+This alters the shape of an API, reducing the shared terminology between service maintainers and their consumers, or even between consumers coming from different languages.
 
-Additionally, by hardcoding even a well-behaved HTTP client into a client library, now consumers are forced to work around that dependency. This may manifest as learning how to use and configure a brand new HTTP client under time pressure, or writing and maintaining brittle [Application Binary Interface (ABI)](https://en.wikipedia.org/wiki/Application_binary_interface)-compatible adapter layers that attempt to use the configuration already present in the rest of the codebase.
+Additionally, by hardcoding even a well-behaved HTTP client into a client library, now consumers are forced to work around that dependency. In the worst case, this could result in a misconfigured underlying library silently falling back to default parameters, or writing and maintaining brittle [Application Binary Interface (ABI)](https://en.wikipedia.org/wiki/Application_binary_interface)-compatible adapter layers that attempt to use the configuration already present in the rest of the codebase.
 
 Once these bespoke HTTP client configurations are built, both they and their dependencies are now added to the grab bag of dependency versions that must be maintained through the life of any given piece of infrastructure. This presents hidden barriers for upgrading all dependencies, as the possibility of transitive dependency conflicts increase as dependency trees become deeper.
-
-<span style="float: right">[Next: Installation](installation)</span>
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,3 @@
+## CLI runner
+
+TODO
diff --git a/...s/scala/akka-http/guardrail-extensions.md → docs/extensions.md b/...s/scala/akka-http/guardrail-extensions.md → docs/extensions.md
@@ -1,8 +1,3 @@
----
-layout: docs
-title: "guardrail extensions - akka-http - scala - guardrail"
----
-
 guardrail Extensions
 ====================
 
@@ -187,5 +182,3 @@ guardrail has [a number of vendor extensions](https://github.com/guardrail-dev/g
     </tr>
   </tbody>
 </table>
-
-<span style="float: left">[Prev: Generating clients](generating-clients)</span>
diff --git a/modules/microsite/docs/img/favicon.png → docs/img/favicon.png b/modules/microsite/docs/img/favicon.png → docs/img/favicon.png
diff --git a/...les/microsite/docs/img/favicon114x114.png → docs/img/favicon114x114.png b/...les/microsite/docs/img/favicon114x114.png → docs/img/favicon114x114.png
diff --git a/...les/microsite/docs/img/favicon120x120.png → docs/img/favicon120x120.png b/...les/microsite/docs/img/favicon120x120.png → docs/img/favicon120x120.png
diff --git a/...les/microsite/docs/img/favicon128x128.png → docs/img/favicon128x128.png b/...les/microsite/docs/img/favicon128x128.png → docs/img/favicon128x128.png
diff --git a/...les/microsite/docs/img/favicon144x144.png → docs/img/favicon144x144.png b/...les/microsite/docs/img/favicon144x144.png → docs/img/favicon144x144.png
diff --git a/...les/microsite/docs/img/favicon150x150.png → docs/img/favicon150x150.png b/...les/microsite/docs/img/favicon150x150.png → docs/img/favicon150x150.png
diff --git a/...les/microsite/docs/img/favicon152x152.png → docs/img/favicon152x152.png b/...les/microsite/docs/img/favicon152x152.png → docs/img/favicon152x152.png
diff --git a/modules/microsite/docs/img/favicon16x16.png → docs/img/favicon16x16.png b/modules/microsite/docs/img/favicon16x16.png → docs/img/favicon16x16.png
diff --git a/...les/microsite/docs/img/favicon196x196.png → docs/img/favicon196x196.png b/...les/microsite/docs/img/favicon196x196.png → docs/img/favicon196x196.png
diff --git a/modules/microsite/docs/img/favicon24x24.png → docs/img/favicon24x24.png b/modules/microsite/docs/img/favicon24x24.png → docs/img/favicon24x24.png
diff --git a/...les/microsite/docs/img/favicon310x150.png → docs/img/favicon310x150.png b/...les/microsite/docs/img/favicon310x150.png → docs/img/favicon310x150.png
diff --git a/...les/microsite/docs/img/favicon310x310.png → docs/img/favicon310x310.png b/...les/microsite/docs/img/favicon310x310.png → docs/img/favicon310x310.png
diff --git a/modules/microsite/docs/img/favicon32x32.png → docs/img/favicon32x32.png b/modules/microsite/docs/img/favicon32x32.png → docs/img/favicon32x32.png
diff --git a/modules/microsite/docs/img/favicon48x48.png → docs/img/favicon48x48.png b/modules/microsite/docs/img/favicon48x48.png → docs/img/favicon48x48.png
diff --git a/modules/microsite/docs/img/favicon57x57.png → docs/img/favicon57x57.png b/modules/microsite/docs/img/favicon57x57.png → docs/img/favicon57x57.png
diff --git a/modules/microsite/docs/img/favicon60x60.png → docs/img/favicon60x60.png b/modules/microsite/docs/img/favicon60x60.png → docs/img/favicon60x60.png
diff --git a/modules/microsite/docs/img/favicon64x64.png → docs/img/favicon64x64.png b/modules/microsite/docs/img/favicon64x64.png → docs/img/favicon64x64.png
diff --git a/modules/microsite/docs/img/favicon70x70.png → docs/img/favicon70x70.png b/modules/microsite/docs/img/favicon70x70.png → docs/img/favicon70x70.png
diff --git a/modules/microsite/docs/img/favicon72x72.png → docs/img/favicon72x72.png b/modules/microsite/docs/img/favicon72x72.png → docs/img/favicon72x72.png
diff --git a/modules/microsite/docs/img/favicon76x76.png → docs/img/favicon76x76.png b/modules/microsite/docs/img/favicon76x76.png → docs/img/favicon76x76.png
diff --git a/modules/microsite/docs/img/favicon96x96.png → docs/img/favicon96x96.png b/modules/microsite/docs/img/favicon96x96.png → docs/img/favicon96x96.png
diff --git a/modules/microsite/docs/img/first_icon.png → docs/img/first_icon.png b/modules/microsite/docs/img/first_icon.png → docs/img/first_icon.png
diff --git a/modules/microsite/docs/img/first_icon2x.png → docs/img/first_icon2x.png b/modules/microsite/docs/img/first_icon2x.png → docs/img/first_icon2x.png
diff --git a/...les/microsite/docs/img/first_icon_raw.png → docs/img/first_icon_raw.png b/...les/microsite/docs/img/first_icon_raw.png → docs/img/first_icon_raw.png
diff --git a/...microsite/docs/img/light_navbar_brand.png → docs/img/light_navbar_brand.png b/...microsite/docs/img/light_navbar_brand.png → docs/img/light_navbar_brand.png
diff --git a/...crosite/docs/img/light_navbar_brand2x.png → docs/img/light_navbar_brand2x.png b/...crosite/docs/img/light_navbar_brand2x.png → docs/img/light_navbar_brand2x.png
diff --git a/modules/microsite/docs/img/navbar_brand.png → docs/img/navbar_brand.png b/modules/microsite/docs/img/navbar_brand.png → docs/img/navbar_brand.png
diff --git a/...les/microsite/docs/img/navbar_brand2x.png → docs/img/navbar_brand2x.png b/...les/microsite/docs/img/navbar_brand2x.png → docs/img/navbar_brand2x.png
diff --git a/modules/microsite/docs/img/second_icon.png → docs/img/second_icon.png b/modules/microsite/docs/img/second_icon.png → docs/img/second_icon.png
diff --git a/modules/microsite/docs/img/second_icon2x.png → docs/img/second_icon2x.png b/modules/microsite/docs/img/second_icon2x.png → docs/img/second_icon2x.png
diff --git a/...es/microsite/docs/img/second_icon_raw.png → docs/img/second_icon_raw.png b/...es/microsite/docs/img/second_icon_raw.png → docs/img/second_icon_raw.png
diff --git a/modules/microsite/docs/img/sidebar_brand.png → docs/img/sidebar_brand.png b/modules/microsite/docs/img/sidebar_brand.png → docs/img/sidebar_brand.png
diff --git a/...es/microsite/docs/img/sidebar_brand2x.png → docs/img/sidebar_brand2x.png b/...es/microsite/docs/img/sidebar_brand2x.png → docs/img/sidebar_brand2x.png
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>guardrail</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="guardrail is a code generation tool, capable of reading from OpenAPI/Swagger specification files and generating high quality source code for a variety of languages and frameworks.">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css" title="docsify-darklight-theme" type="text/css" />
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'guardrail',
+      repo: 'https://github.com/guardrail-dev/guardrail',
+      loadSidebar: true,
+      themeColor: '#3F51B5',
+      subMaxLevel: 3,
+      auto2top: true,
+      ga: 'G-L51EVMQF15',
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js" type="text/javascript"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
+</body>
+</html>