Import docs from the Meta website (#33)

* Initial import of Analysis docs

* Add projects to Gradle and scripts

* Rename buildMetaDoc Gradle task to buildDoc

* Add job for generating documentation site

* Test job for generating documentation site

* Remove job dependency in test

* Install bundler tool

* Remove unnecessary files

* Remove test for publishing documentation

Co-authored-by: franciscodr <[email protected]>

.github/workflows/publish.yml

@@ -116,4 +116,46 @@ jobs:
       run: ./gradlew --full-stacktrace publishPlugins
 
     - name: Stop Gradle daemons
-      run: ./gradlew --stop
+      run: ./gradlew --stop
+
+  publish_documentation:
+    needs: build
+    runs-on: ubuntu-latest
+
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_CLOUDFRONT_ID: ${{ secrets.AWS_CLOUDFRONT_ID }}
+      AWS_DEFAULT_REGION: eu-west-1
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      JEKYLL_ENV: production
+      S3_BUCKET: ${{ secrets.S3_BUCKET }}
+
+    steps:
+      - uses: actions/[email protected]
+
+      - uses: actions/[email protected]
+        with:
+          distribution: 'adopt'
+          java-version: '15'
+          cache: 'gradle'
+
+      - name: Prepare environment
+        run: |
+          sudo gem install bundler
+          bundle config set --local path 'vendor/bundle'
+          bundle install --gemfile docs/Gemfile
+
+      - name: Create API Doc and validate
+        run: ./gradlew buildDoc
+
+      - name: Generate site
+        run: bundle exec jekyll build -b docs/analysis -s docs/docs -d docs/build/_site
+
+      - name: Upload site to S3 bucket
+        run: aws s3 sync --delete docs/build/_site s3://$S3_BUCKET/docs/analysis
+
+      - name: Invalidate CloudFront cache
+        run: aws cloudfront create-invalidation --distribution-id $AWS_CLOUDFRONT_ID --paths "/docs/analysis"
+
+      - name: Stop Gradle daemons
+        run: ./gradlew --stop

README.md

@@ -1,20 +1,18 @@
 # Λrrow Analysis
 
-[![Kotlin version badge](https://img.shields.io/badge/kotlin-1.6-blue.svg)](https://kotlinlang.org/docs/whatsnew16.html)
+[![Kotlin version badge](https://img.shields.io/badge/kotlin-1.6.20-blue.svg)](https://kotlinlang.org/docs/whatsnew16.html)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 [![Maven Central](https://img.shields.io/maven-central/v/io.arrow-kt/arrow-analysis-common?color=4caf50&label=latest%20release)](https://maven-badges.herokuapp.com/maven-central/io.arrow-kt/arrow-analysis-common)
 ## Contributing
 
-Λrrow Meta is an inclusive community powered by awesome individuals like you. As an actively growing ecosystem, Λrrow Meta and its associated libraries and toolsets are in need of new contributors! We have issues suited for all levels, from entry to advanced, and our maintainers are happy to provide 1:1 mentoring. All are welcome in Λrrow Meta.
-
-If you’re looking to contribute, have questions, or want to keep up-to-date about what’s happening, please follow us here and say hello!
+Λrrow is an inclusive community powered by awesome individuals like you. If you’re looking to contribute, have questions, or want to keep up-to-date about what’s happening, please follow us here and say hello!
 
 - [#arrow-meta on Kotlin Slack](https://kotlinlang.slack.com/)
 
-## Licence
+## License
 
 ```
-Copyright (C) 2017 The Λrrow Authors
+Copyright (C) 2017 - 2022 The Λrrow Authors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

build.gradle.kts

@@ -18,6 +18,22 @@ allprojects {
   group = property("projects.group").toString()
 }
 
+tasks {
+  create<Exec>("generateDoc") {
+    commandLine("sh", "gradlew", "dokkaJekyll")
+  }
+
+  create("buildDoc") {
+    group = "documentation"
+    description = "Generates API Doc and validates all the documentation"
+    dependsOn("generateDoc")
+  }
+}
+
+allprojects {
+  extra.set("dokka.outputDirectory", rootDir.resolve("docs/docs/apidocs"))
+}
+
 allprojects {
   this.tasks.withType<Test>() {
     useJUnitPlatform()

docs/.gitignore

@@ -0,0 +1,15 @@
+build
+
+## Jekyll
+_site
+.sass-cache
+.jekyll-metadata
+.jekyll-cache
+
+## OSX bullshit
+.DS_Store
+
+## Ruby environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/

docs/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.2.0"
+gem "kramdown", ">= 2.3.1"

docs/Gemfile.lock

@@ -0,0 +1,73 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.8)
+    em-websocket (0.5.2)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    eventmachine (1.2.7-x64-mingw32)
+    ffi (1.15.0)
+    ffi (1.15.0-x64-mingw32)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.6.0)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.0)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-sass-converter (2.1.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.3.1)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.5.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.26.0)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    sassc (2.4.0-x64-mingw32)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  ruby
+  x64-mingw32
+
+DEPENDENCIES
+  jekyll (~> 4.2.0)
+  kramdown (>= 2.3.1)
+
+BUNDLED WITH
+   2.1.4

docs/README.md

@@ -0,0 +1,38 @@
+---
+layout: docs
+title: Async
+permalink: /docs/effects/async/
+---
+
+# Documentation
+
+## Prerequisites
+
+<details>
+  <summary>System requirements:</summary>
+  <p>
+
+   _You just need to do this one time in case you have problems building the site_
+  </p>
+</details>
+
+* `ruby` >= 2.4.0 (check [rvm.io](https://rvm.io/) on the best way to install `ruby` on your system)
+* `rubygems` >= 2.5.0 (`gem update --system` will update your `ruby` ecosystem)
+* `bundler` >= 2.0.0 (`gem install bundler` will install the latest version)
+
+
+
+## Build and run in your local environment
+
+Run `build-and-run-website.sh` script which is located in `scripts` directory.
+
+It can be executed from any directory:
+
+```
+$> ./scripts/build-and-run-website.sh
+```
+
+```
+$> cd scripts
+$> ./build-and-run-website.sh
+```

docs/build.gradle.kts

@@ -0,0 +1,25 @@
+buildscript {
+  repositories {
+    mavenCentral()
+  }
+}
+
+plugins {
+  id(libs.plugins.kotlin.jvm.get().pluginId)
+  alias(libs.plugins.arrowGradleConfig.kotlin)
+}
+
+dependencies {
+  runtimeOnly(libs.kotlin.stdlibJDK8)
+  runtimeOnly(projects.arrowAnalysisTypes)
+}
+
+tasks {
+  named<Delete>("clean") {
+    delete("$rootDir/docs/docs/apidocs")
+  }
+
+  compileKotlin {
+    kotlinOptions.freeCompilerArgs += listOf("-Xskip-runtime-version-check")
+  }
+}

docs/docs/_config.yml

@@ -0,0 +1,32 @@
+title: Arrow Analysis
+#-------------------------
+name: Λrrow Analysis
+#-------------------------
+description: Pre-, post-condition, and invariant checks for your Kotlin code
+#-------------------------
+author: The Λrrow Authors
+keywords: functional-programming, kotlin-library, static-analysis, contracts
+#-------------------------
+url: https://arrow-kt.io/docs/analysis
+#-------------------------
+arrow_url: https://arrow-kt.io
+#-------------------------
+github_repo: https://github.com/arrow-kt/arrow-analysis
+#-------------------------
+twitter_handle: "@arrow_kt"
+#-------------------------
+slack_kotlin_channel: "https://slack.kotlinlang.org"
+slack_arrow_channel: "https://kotlinlang.slack.com/archives/C5UPMM0A0"
+#-------------------------
+markdown: kramdown
+sass:
+    style: compressed
+#-------------------------
+exclude: ['config.ru', 'Gemfile', 'Gemfile.lock', 'vendor', 'Procfile', 'Rakefile', 'build', 'build.gradle.kts', 'gradle.properties']
+#-------------------------
+defaults:
+  - scope:
+      path: "apidocs"
+      type: "pages"
+    values:
+      layout: "docs-analysis"

docs/docs/_data/analysis/features.yml

@@ -0,0 +1,15 @@
+content:
+    - title: Quickstart
+      url: https://arrow-kt.io/docs/quickstart/
+
+    - title: Core
+      url: https://arrow-kt.io/docs/core/
+
+    - title: FX
+      url: https://arrow-kt.io/docs/fx/
+
+    - title: Optics
+      url: https://arrow-kt.io/docs/optics/dsl/
+
+    - title: Meta
+      url: https://arrow-kt.io/docs/meta/

docs/docs/_data/analysis/sidebar.yml

@@ -0,0 +1,30 @@
+options:
+    - title: Quick Start
+      url: /
+
+    - title: Pre and post-conditions
+      url: /conditions
+
+    - title: Control operators (if, when)
+      url: /control
+
+    - title: Mutability and loops
+      url: /mutability
+
+    - title: Types and invariants
+      url: /types
+
+    - title: Wrappers
+      url: /wrappers
+
+    - title: Fields
+      url: /fields
+
+    - title: 3rd-party libraries
+      url: /laws
+
+    - title: Java support
+      url: /java
+
+    - title: GitHub Actions / SARIF
+      url: /sarif

docs/docs/_includes/_doc.html

@@ -0,0 +1,27 @@
+<div id="doc-wrapper">
+  <div class="doc-header">
+    <button type="button" id="main-toggle" class="sidebar-toggle">
+      <i class="fa fa-lg fa-bars menu-icon"></i>
+    </button>
+    <div class="search-wrapper">
+      <img src="{{ '/img/search-icon.svg' | relative_url }}" title="search" alt="Search">
+      <input id="docsearch" class="search" placeholder="Search documentation..." type="search">
+    </div>
+    <ul class="menu-doc-search">
+      <li>
+        <a class="menu-links" href="{{ site.github_repo }}" title="Github">Github</a>
+      </li>
+      <li>
+      <div class="doc-stars-container">
+        <a class="github-button" href="https://github.com/arrow-kt/arrow" data-color-scheme="no-preference: light; light: light; dark: light;" data-size="large" data-show-count="true" aria-label="Star arrow-kt/arrow on GitHub">Arrow Org</a>
+      </div>
+      </li>
+    </ul>
+  </div>
+  <div class="doc-content">
+    {% if page.video %}
+    {% include _media-wrapper.html id=page.video %}
+    {% endif %}
+    {{ content }}
+  </div>
+</div>

docs/docs/_includes/_github-modal.html

@@ -0,0 +1,18 @@
+<div id="star-modal">
+    <div class="stars-text-line">
+      <p>Do you like Arrow?</p>
+      <span class="close-modal" title="Close panel">✖</span>
+    </div>
+    <a class="github-button" href="https://github.com/arrow-kt/arrow" data-color-scheme="no-preference: light; light: light; dark: light;" data-size="large" data-show-count="true" aria-label="Star arrow-kt/arrow on GitHub">Arrow Org</a>
+    <script>
+      if (sessionStorage.getItem("dismissed") !== "true") {
+        setTimeout(function () {
+            document.querySelector("#star-modal").classList.add("in");
+        }, 15000);
+        document.querySelector("#star-modal .close-modal").addEventListener("click", function () {
+            document.querySelector("#star-modal").classList.add("out");
+            sessionStorage.setItem("dismissed", "true");
+        });
+      }
+    </script>
+</div>