docs: revamp documentation (#152)

* docs: revamp documentation * docs: fix broken links
raystack · Jun 16, 2022 · de3b943 · de3b943
1 parent 753f5f9
commit de3b943
Show file tree

Hide file tree

Showing 40 changed files with 8,426 additions and 104 deletions.
diff --git a/.gitbook.yaml b/.gitbook.yaml
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,33 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+      - name: Installation
+        uses: bahmutov/npm-install@v1
+        with:
+          install-command: yarn
+          working-directory: docs
+      - name: Build docs
+        working-directory: docs
+        run: cd docs && yarn build
+      - name: Deploy docs
+        env:
+          GIT_USER: ravisuhag
+          GIT_PASS: ${{ secrets.DOCU_RS_TOKEN }}
+          DEPLOYMENT_BRANCH: gh-pages
+          CURRENT_BRANCH: master
+        working-directory: docs
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "ravisuhag"
+          yarn deploy
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -8,32 +8,27 @@
 
 Compass is a search and discovery engine built for querying application deployments, datasets and meta resources. It can also optionally track data flow relationships between these resources and allow the user to view a representation of the data flow graph.
 
-```
-Notes
----
-Compass was previously called 'Columbus'. We we were migrating to the new name to accomodate our current and future use cases considering this platform does not only about metadata discovery and lineage but also revolve around metadata management. 
-```
-
-<p align="center"><img src="./docs/assets/overview.svg" /></p>
+<p align="center"><img src="./docs/static/assets/overview.svg" /></p>
 
 ## Key Features
+
 Discover why users choose Compass as their main data discovery and lineage service
 
-* **Full text search** Faster and better search results powered by ElasticSearch full text search capability.
-* **Search Tuning** Narrow down your search results by adding filters, getting your crisp results.
-* **Data Lineage** Understand the relationship between metadata with data lineage interface.
-* **Scale:** Compass scales in an instant, both vertically and horizontally for high performance.
-* **Extensibility:** Add your own metadata types and resources to support wide variety of metadata.
-* **Runtime:** Compass can run inside VMs or containers in a fully managed runtime environment like kubernetes.
+- **Full text search** Faster and better search results powered by ElasticSearch full text search capability.
+- **Search Tuning** Narrow down your search results by adding filters, getting your crisp results.
+- **Data Lineage** Understand the relationship between metadata with data lineage interface.
+- **Scale:** Compass scales in an instant, both vertically and horizontally for high performance.
+- **Extensibility:** Add your own metadata types and resources to support wide variety of metadata.
+- **Runtime:** Compass can run inside VMs or containers in a fully managed runtime environment like kubernetes.
 
 ## Usage
 
 Explore the following resources to get started with Compass:
 
-* [Guides](docs/guides) provides guidance on ingesting and querying metadata from Compass.
-* [Concepts](docs/concepts) describes all important Compass concepts.
-* [Reference](docs/reference) contains details about configurations, metrics and other aspects of Compass.
-* [Contribute](docs/contribute/contribution.md) contains resources for anyone who wants to contribute to Compass.
+- [Guides](https://odpf.github.io/compass/docs/guides) provides guidance on ingesting and querying metadata from Compass.
+- [Concepts](https://odpf.github.io/compass/docs/concepts) describes all important Compass concepts.
+- [Reference](https://odpf.github.io/compass/docs/reference) contains details about configurations, metrics and other aspects of Compass.
+- [Contribute](https://odpf.github.io/compass/docs/contribute/contribution.md) contains resources for anyone who wants to contribute to Compass.
 
 ## Requirements
 
@@ -52,14 +47,15 @@ Go to the root of this project and run `docker-compose`.
 ```text
 $ docker-compose up
 ```
+
 Once postgres and elasticsearch has been ready, we can run Compass by passing in the config of postgres and elasticsearch defined in `docker-compose.yaml` file.
 
 ## Building Compass
 
 Begin by cloning this repository then you have two ways in which you can build compass
 
-* As a native executable
-* As a docker image
+- As a native executable
+- As a docker image
 
 To build compass as a native executable, run `make` inside the cloned repository.
 
@@ -76,13 +72,15 @@ $ docker build . -t compass
 ```
 
 ## Migration
+
 Before serving Compass app, we need to run the migration first. Run this docker command to migrate Compass.
 
 ```text
 $ docker run --rm --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://es:9200 -e DB_HOST=postgres -e DB_PORT=5432 -e DB_NAME=compass -e DB_USER=compass -e DB_PASSWORD=compass_password odpf/compass compass migrate
 ```
 
 If you are using Compass binary, you can run this command.
+
 ```text
 ./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> migrate"
 ```
@@ -96,11 +94,13 @@ $ docker run --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://
 ```
 
 If you are using Compass binary, you can run this command.
+
 ```text
 ./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> serve"
 ```
 
 If everything goes ok, you should see something like this:
+
 ```text
 time="2022-04-27T09:18:08Z" level=info msg="compass starting" version=v0.2.0
 time="2022-04-27T09:18:08Z" level=info msg="connected to elasticsearch cluster" config="\"docker-cluster\" (server version 7.6.1)"
@@ -109,26 +109,27 @@ time="2022-04-27T09:18:08Z" level=info msg="statsd metrics monitoring is disable
 time="2022-04-27T09:18:08Z" level=info msg="connected to postgres server" host=postgres port=5432
 time="2022-04-27T09:18:08Z" level=info msg="server started"
 ```
+
 ## Running tests
 
 ```
 # Run tests
 $ make test
 ```
 
-The tests combine both unit and integration tests, the test suite requires docker to run elasticsearch. In case you wish to test against an existing 
+The tests combine both unit and integration tests, the test suite requires docker to run elasticsearch. In case you wish to test against an existing
 elasticsearch cluster, set the value of `ES_TEST_SERVER_URL` to the URL of the elasticsearch server.
 
-
 ## Contribute
 
 Development of Compass happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving Compass.
 
-Read our [contributing guide](docs/contribute/contribution.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Compass.
+Read our [contributing guide](https://odpf.github.io/compass/docs/contribute/contribution.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Compass.
 
 To help you get your feet wet and get you familiar with our contribution process, we have a list of [good first issues](https://github.com/odpf/compass/labels/good%20first%20issue) that contain bugs which have a relatively limited scope. This is a great place to get started.
 
 This project exists thanks to all the [contributors](https://github.com/odpf/compass/graphs/contributors).
 
 ## License
+
 Compass is [Apache 2.0](LICENSE) licensed.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
@@ -1,26 +1,33 @@
-# Introduction
+# Website
 
-Compass is a search and discovery engine built for querying application deployments, datasets and meta resources. It can also optionally track data flow relationships between these resources and allow the user to view a representation of the data flow graph.
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 
-![](.gitbook/assets/overview.svg)
+### Installation
 
-## Key Features
+```
+$ yarn
+```
 
-Discover why users choose Compass as their main data discovery and lineage service
+### Local Development
 
-* **Full text search** Faster and better search results powered by ElasticSearch full text search capability.
-* **Search Tuning** Narrow down your search results by adding filters, getting your crisp results.
-* **Data Lineage** Understand the relationship between metadata with data lineage interface.
-* **Scale:** Compass scales in an instant, both vertically and horizontally for high performance.
-* **Extensibility:** Add your own metadata types and resources to support wide variety of metadata.
-* **Runtime:** Compass can run inside VMs or containers in a fully managed runtime environment like kubernetes.
+```
+$ yarn start
+```
 
-## Usage
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-Explore the following resources to get started with Compass:
+### Build
 
-* [Guides](https://github.com/odpf/compass/tree/main/docs/guides) provides guidance on ingesting and queying metadata from Compass.
-* [Concepts](https://github.com/odpf/compass/tree/main/docs/concepts) describes all important Compass concepts.
-* [Reference](https://github.com/odpf/compass/tree/main/docs/reference) contains details about configurations, metrics and other aspects of Compass.
-* [Contribute](https://github.com/odpf/compass/tree/main/docs/contribute) contains resources for anyone who wants to contribute to Compass.
+```
+$ yarn build
+```
 
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
diff --git a/docs/babel.config.js b/docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/concepts/architecture.md → docs/docs/concepts/architecture.md b/docs/concepts/architecture.md → docs/docs/concepts/architecture.md
@@ -2,21 +2,25 @@
 
 Compass' architecture is pretty simple. It has a client-server architecture backed by PostgreSQL as a main storage and Elasticsearch as a secondary storage and provides HTTP & gRPC interface to interact with.
 
-![Compass Architecture](../assets/architecture.png)
+![Compass Architecture](/assets/architecture.png)
 
 ## System Design
+
 ### Components
 
 #### gRPC Server
 
-* gRPC server is the main interface to interact with Compass.
-* The protobuf file to define the interface is centralized in [odpf/proton](https://github.com/odpf/proton/tree/main/odpf/compass/v1beta1)
+- gRPC server is the main interface to interact with Compass.
+- The protobuf file to define the interface is centralized in [odpf/proton](https://github.com/odpf/proton/tree/main/odpf/compass/v1beta1)
+
 #### gRPC-gateway Server
 
-* gRPC-gateway server transcodes HTTP call to gRPC call and allows client to interact with Compass using RESTful HTTP request.
+- gRPC-gateway server transcodes HTTP call to gRPC call and allows client to interact with Compass using RESTful HTTP request.
+
 #### PostgreSQL
 
-* Compass uses PostgreSQL as it is main storage for storing all of its metadata.
+- Compass uses PostgreSQL as it is main storage for storing all of its metadata.
+
 #### Elasticsearch
 
-* Compass uses Elasticsearch as it is secondary storage to power search of metadata.
+- Compass uses Elasticsearch as it is secondary storage to power search of metadata.
diff --git a/docs/concepts/internals.md → docs/docs/concepts/internals.md b/docs/concepts/internals.md → docs/docs/concepts/internals.md
diff --git a/docs/concepts/overview.md → docs/docs/concepts/overview.md b/docs/concepts/overview.md → docs/docs/concepts/overview.md
diff --git a/docs/concepts/user.md → docs/docs/concepts/user.md b/docs/concepts/user.md → docs/docs/concepts/user.md
diff --git a/docs/contribute/contributing.md → docs/docs/contribute/contributing.md b/docs/contribute/contributing.md → docs/docs/contribute/contributing.md
diff --git a/docs/contribute/development-guide.md → docs/docs/contribute/development-guide.md b/docs/contribute/development-guide.md → docs/docs/contribute/development-guide.md
diff --git a/docs/guides/discussion.md → docs/docs/guides/discussion.md b/docs/guides/discussion.md → docs/docs/guides/discussion.md
diff --git a/docs/guides/ingestion.md → docs/docs/guides/ingestion.md b/docs/guides/ingestion.md → docs/docs/guides/ingestion.md
diff --git a/docs/guides/installation.md → docs/docs/guides/installation.md b/docs/guides/installation.md → docs/docs/guides/installation.md
diff --git a/docs/guides/querying.md → docs/docs/guides/querying.md b/docs/guides/querying.md → docs/docs/guides/querying.md
diff --git a/docs/guides/starring.md → docs/docs/guides/starring.md b/docs/guides/starring.md → docs/docs/guides/starring.md
diff --git a/docs/guides/tagging.md → docs/docs/guides/tagging.md b/docs/guides/tagging.md → docs/docs/guides/tagging.md
diff --git a/docs/guides/telemetry.md → docs/docs/guides/telemetry.md b/docs/guides/telemetry.md → docs/docs/guides/telemetry.md
diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md
@@ -0,0 +1,30 @@
+---
+id: introduction
+slug: /
+---
+
+# Introduction
+
+Compass is a search and discovery engine built for querying application deployments, datasets and meta resources. It can also optionally track data flow relationships between these resources and allow the user to view a representation of the data flow graph.
+
+![](/assets/overview.svg)
+
+## Key Features
+
+Discover why users choose Compass as their main data discovery and lineage service
+
+- **Full text search** Faster and better search results powered by ElasticSearch full text search capability.
+- **Search Tuning** Narrow down your search results by adding filters, getting your crisp results.
+- **Data Lineage** Understand the relationship between metadata with data lineage interface.
+- **Scale:** Compass scales in an instant, both vertically and horizontally for high performance.
+- **Extensibility:** Add your own metadata types and resources to support wide variety of metadata.
+- **Runtime:** Compass can run inside VMs or containers in a fully managed runtime environment like kubernetes.
+
+## Usage
+
+Explore the following resources to get started with Compass:
+
+- [Guides](./guides/ingestion) provides guidance on ingesting and queying metadata from Compass.
+- [Concepts](./concepts/overview) describes all important Compass concepts.
+- [Reference](./reference/configuration.md) contains details about configurations, metrics and other aspects of Compass.
+- [Contribute](./contribute/contributing.md) contains resources for anyone who wants to contribute to Compass.
diff --git a/docs/reference/api.md → docs/docs/reference/api.md b/docs/reference/api.md → docs/docs/reference/api.md
diff --git a/docs/reference/configuration.md → docs/docs/reference/configuration.md b/docs/reference/configuration.md → docs/docs/reference/configuration.md
diff --git a/docs/roadmap.md → docs/docs/roadmap.md b/docs/roadmap.md → docs/docs/roadmap.md