Set up mdoc (#9)

azavea · Nov 5, 2019 · 01e29ea · 01e29ea
1 parent 97b90e5
commit 01e29ea
Show file tree

Hide file tree

Showing 31 changed files with 7,631 additions and 3 deletions.
diff --git a/.gitignore b/.gitignore
@@ -118,3 +118,7 @@ scratch/
 stats.json
 app-lambda/opt/*
 /app-lambda/package.sh
+
+# js files from docusaurus
+node_modules/*
+website/build/*
diff --git a/build.sbt b/build.sbt
@@ -132,3 +132,16 @@ lazy val api = (project in file("api"))
   .settings({
     libraryDependencies ++= apiDependencies
   })
+
+//////////
+// DOCS //
+//////////
+lazy val docs = (project in file("api-docs"))
+  .dependsOn(api)
+  .enablePlugins(MdocPlugin)
+  .enablePlugins(MdocPlugin, DocusaurusPlugin)
+  .settings(
+    mdocVariables := Map(
+      "VERSION" -> version.value
+    )
+  )
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -15,8 +15,6 @@ services:
 
   api:
     image: openjdk:11-jdk
-    command:
-      - "api/run"
     depends_on:
       database:
         condition: service_healthy

diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,3 @@
+# Development
+
+coming soon
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -0,0 +1,63 @@
+# `franklin`
+
+## What's `franklin`?
+
+A [STAC](https://github.com/radiantearth/stac-spec) and [OGC API Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) compliant web service focused on ease-of-use for end-users.
+
+`franklin` imports and serves STAC catalogs backed by Postgres. Its goal is to enable import and querying of STAC catalogs in a single statement.
+
+## How do I get it?
+
+### With a Postgres database that already exists
+
+A runnable version of `franklin` is published as a docker container. You can run it with:
+
+```bash
+$ docker run quay.io/azavea/franklin:latest server \
+   --db-host <database-host> \
+   --db-password <password> \
+   --db-name <database-name>
+```
+
+### Standalone
+
+To bring up a standalone version to explore a STAC catalog locally, you can, with `docker-compose`,
+`docker-compose up` with this `docker-compose.yml`:
+
+```yaml
+version: '2.3'
+services:
+  database:
+    image: quay.io/azavea/postgis:2.3-postgres9.6-slim
+    environment:
+      - POSTGRES_USER=franklin
+      - POSTGRES_PASSWORD=franklin
+      - POSTGRES_DB=franklin
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "franklin"]
+      interval: 3s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+
+  api:
+    image: quay.io/azavea/franklin:latest
+    depends_on:
+      database:
+        condition: service_healthy
+	command:
+	  - server
+    environment:
+      - AWS_PROFILE
+      - ENVIRONMENT=development
+      - POSTGRES_URL=jdbc:postgresql://database.service.internal/
+      - POSTGRES_NAME=franklin
+      - POSTGRES_USER=franklin
+      - POSTGRES_PASSWORD=franklin
+    links:
+      - database:database.service.internal
+    ports:
+      - "9090:9090"
+```
+
+You can then view api documentation for `franklin` at `:9090/api/docs.yaml`.
diff --git a/project/plugins.sbt b/project/plugins.sbt
@@ -9,3 +9,4 @@ addSbtPlugin("com.eed3si9n"           % "sbt-assembly"             % "0.14.9")
 addSbtPlugin("org.scala-js"           % "sbt-scalajs"              % "0.6.26")
 addSbtPlugin("ch.epfl.scala"          % "sbt-scalajs-bundler"      % "0.14.0")
 addSbtPlugin("org.portable-scala"     % "sbt-scalajs-crossproject" % "0.6.0")
+addSbtPlugin("org.scalameta"          % "sbt-mdoc"                 % "2.0.0")
diff --git a/scripts/test b/scripts/test
@@ -40,7 +40,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
         if [[ $CI ]]; then
             pushd "${DIR}"
 
-            ./sbt "; scalafix --check; test"
+            ./sbt "; scalafix --check; test; docs/mdoc --check"
 
             popd
         else

diff --git a/website/README.md b/website/README.md
@@ -0,0 +1,193 @@
+This website was created with [Docusaurus](https://docusaurus.io/).
+
+# What's In This Document
+
+* [Get Started in 5 Minutes](#get-started-in-5-minutes)
+* [Directory Structure](#directory-structure)
+* [Editing Content](#editing-content)
+* [Adding Content](#adding-content)
+* [Full Documentation](#full-documentation)
+
+# Get Started in 5 Minutes
+
+1. Make sure all the dependencies for the website are installed:
+
+```sh
+# Install dependencies
+$ yarn
+```
+2. Run your dev server:
+
+```sh
+# Start the site
+$ yarn start
+```
+
+## Directory Structure
+
+Your project file structure should look something like this
+
+```
+my-docusaurus/
+  docs/
+    doc-1.md
+    doc-2.md
+    doc-3.md
+  website/
+    blog/
+      2016-3-11-oldest-post.md
+      2017-10-24-newest-post.md
+    core/
+    node_modules/
+    pages/
+    static/
+      css/
+      img/
+    package.json
+    sidebar.json
+    siteConfig.js
+```
+
+# Editing Content
+
+## Editing an existing docs page
+
+Edit docs by navigating to `docs/` and editing the corresponding document:
+
+`docs/doc-to-be-edited.md`
+
+```markdown
+---
+id: page-needs-edit
+title: This Doc Needs To Be Edited
+---
+
+Edit me...
+```
+
+For more information about docs, click [here](https://docusaurus.io/docs/en/navigation)
+
+## Editing an existing blog post
+
+Edit blog posts by navigating to `website/blog` and editing the corresponding post:
+
+`website/blog/post-to-be-edited.md`
+```markdown
+---
+id: post-needs-edit
+title: This Blog Post Needs To Be Edited
+---
+
+Edit me...
+```
+
+For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
+
+# Adding Content
+
+## Adding a new docs page to an existing sidebar
+
+1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`:
+
+```md
+---
+id: newly-created-doc
+title: This Doc Needs To Be Edited
+---
+
+My new content here..
+```
+
+1. Refer to that doc's ID in an existing sidebar in `website/sidebar.json`:
+
+```javascript
+// Add newly-created-doc to the Getting Started category of docs
+{
+  "docs": {
+    "Getting Started": [
+      "quick-start",
+      "newly-created-doc" // new doc here
+    ],
+    ...
+  },
+  ...
+}
+```
+
+For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation)
+
+## Adding a new blog post
+
+1. Make sure there is a header link to your blog in `website/siteConfig.js`:
+
+`website/siteConfig.js`
+```javascript
+headerLinks: [
+    ...
+    { blog: true, label: 'Blog' },
+    ...
+]
+```
+
+2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`:
+
+`website/blog/2018-05-21-New-Blog-Post.md`
+
+```markdown
+---
+author: Frank Li
+authorURL: https://twitter.com/foobarbaz
+authorFBID: 503283835
+title: New Blog Post
+---
+
+Lorem Ipsum...
+```
+
+For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
+
+## Adding items to your site's top navigation bar
+
+1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`:
+
+`website/siteConfig.js`
+```javascript
+{
+  headerLinks: [
+    ...
+    /* you can add docs */
+    { doc: 'my-examples', label: 'Examples' },
+    /* you can add custom pages */
+    { page: 'help', label: 'Help' },
+    /* you can add external links */
+    { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
+    ...
+  ],
+  ...
+}
+```
+
+For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation)
+
+## Adding custom pages
+
+1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`:
+1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element:
+
+`website/siteConfig.js`
+```javascript
+{
+  headerLinks: [
+    ...
+    { page: 'my-new-custom-page', label: 'My New Custom Page' },
+    ...
+  ],
+  ...
+}
+```
+
+For more information about custom pages, click [here](https://docusaurus.io/docs/en/custom-pages).
+
+# Full Documentation
+
+Full documentation can be found on the [website](https://docusaurus.io/).