devstream-io · daniel-hutao · Apr 7, 2022 · Apr 7, 2022
diff --git a/docs/best_practices.md b/docs/best_practices.md
@@ -0,0 +1,8 @@
+# Best Practices
+
+```{toctree}
+---
+maxdepth: 1
+---
+best_practices/gitops
+```
diff --git a/docs/best_practices/gitops.md b/docs/best_practices/gitops.md
@@ -110,3 +110,9 @@ and you should see similar output:
 2022-03-11 13:39:11 ✔ [SUCCESS]  All plugins destroyed successfully.
 2022-03-11 13:39:11 ✔ [SUCCESS]  Destroy finished.
 ```
+
+```{toctree}
+---
+maxdepth: 1
+---
+```
diff --git a/docs/commands_in_detail/verify.md b/docs/commands_in_detail/verify.md
@@ -23,7 +23,7 @@ If not, it tries to give you a hint that maybe you forgot to run `dtm init` firs
 
 ## 4. Config / State / Resource
 
-For definitions of _Config_, _State_, and _Resource_, see the [config_state_resource_explanation.md](../config_state_resource_explanation.md).
+For definitions of _Config_, _State_, and _Resource_, see the [config_state_resource_explanation.md](../core_concepts.md).
 
 `dtm verify` tries to see if the _Config_ matches the _State_ and the _Resource_ or not. If not, it tells you what exactly is not the same, and what would happen if you run `dtm apply`.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -6,8 +6,8 @@
 copyright = '2022, Merico'
 author = 'Merico'
 
-release = '0.2'
-version = '0.2.0'
+release = '0.3.2'
+version = '0.3.2'
 
 # -- General configuration
 

diff --git a/docs/creating_a_document.md b/docs/creating_a_document.md
@@ -0,0 +1,64 @@
+# Creating a Document
+
+## Dependencies
+
+```shell
+brew install python
+pip3 install sphinx sphinx-rtd-theme
+cd docs
+pip3 install -r requirements.txt
+```
+
+## Locally Build Docs and View
+
+```shell
+cd docs
+rm -rf build
+make html
+open build/html/index.html
+```
+
+## Where to Put a Document
+
+### Top Level Document
+
+Put it under docs/*.md, if it's a top-level document.
+
+## Non Top Level Document
+
+Put it under:
+- docs/best_practices/*.md, if it's a "best practice" type of documentation
+- docs/commands_in_detail/*.md, if it's related to `dtm` commands
+- docs/plugins/*.md, if it's a doc of a plugin
+
+## Table of Content
+
+### Top Level Document
+
+In `index.md`, add the name of the file (without .md) into the "toctree" part (order matters).
+
+### Non Top Level Document
+
+There should be a top level document for non-top level documents, and of course that top level document should be in the table of content in `index.md`.
+
+In this top level document, there should be a sub table of content.
+
+See `plugins.md` and `plugins/*.md` for an example.
+
+## Document Titles
+
+Always use H1 (#) as the title of the document. There should only be one H1 (#) per doc.
+
+Use H2 (##), H3 (###), etc., accordingly.
+
+## Add the Doc to the Table of Content
+
+Always put the following at the end of your doc:
+
+````yaml
+```{toctree}
+---
+maxdepth: 1
+---
+```
+````
diff --git a/docs/index.md b/docs/index.md
@@ -12,9 +12,12 @@ architecture
 core_concepts
 output
 commands_explained
+plugins
 development_workflow
 project_layout
 creating_a_plugin
+best_practices
+creating_a_document
 roadmap
 Releases ⧉ <https://github.com/devstream-io/devstream/releases>
 Blog ⧉ <https://blog.dtm.dev>

diff --git a/docs/plugins.md b/docs/plugins.md
@@ -0,0 +1,23 @@
+# Plugins
+
+All plugins documents:
+
+```{toctree}
+---
+maxdepth: 1
+---
+plugins/argocd
+plugins/argocdapp
+plugins/devlake
+plugins/github-repo-scaffolding-golang
+plugins/githubactions-golang
+plugins/githubactions-nodejs
+plugins/githubactions-python
+plugins/gitlabci-golang
+plugins/jenkins
+plugins/jira-github-integ
+plugins/kube-prometheus
+plugins/openldap
+plugins/trello-github-integ
+plugins/trello
+```
diff --git a/docs/plugins/argocd.md b/docs/plugins/argocd.md
@@ -1,8 +1,8 @@
-## 1 `argocd` Plugin
+# `argocd` Plugin
 
 This plugin installs [ArgoCD](https://argoproj.github.io/cd/) in an existing Kubernetes cluster using the Helm chart.
 
-## 2 Usage:
+## Usage:
 
 ```yaml
 tools:

diff --git a/docs/plugins/argocdapp.md b/docs/plugins/argocdapp.md
@@ -1,4 +1,4 @@
-## 1 `argocdapp` Plugin
+# `argocdapp` Plugin
 
 This plugin creates an [ArgoCD Application](https://argo-cd.readthedocs.io/en/stable/core_concepts/) custom resource.
 
@@ -9,7 +9,8 @@ This plugin creates an [ArgoCD Application](https://argo-cd.readthedocs.io/en/st
   See [GitOps Toolchain](../best_practices/gitops.md) for more info.
 - Currently, only the Helm chart is supported when creating the ArgoCD application.
 - Modify the file accordingly. Especially remember to modify `ARGOCD_TOOL_NAME`.
-## 2 Usage:
+
+## Usage:
 
 ```yaml
 tools:
@@ -42,7 +43,7 @@ tools:
       repoURL: https://github.com/ironcore864/openstream-gitops-test.git
 ```
 
-## 3. Use Together with the `github-repo-scaffolding-golang` Plugin
+## Use Together with the `github-repo-scaffolding-golang` Plugin
 
 This plugin can be used together with the `github-repo-scaffolding-golang` plugin (see document [here](./github-repo-scaffolding-golang.md).)
 

diff --git a/docs/plugins/devlake.md b/docs/plugins/devlake.md
@@ -1,10 +1,10 @@
-## 1 `devlake` Plugin
+# `devlake` Plugin
 
 This plugin installs [DevLake](https://github.com/merico-dev/lake) in an existing K8s cluster.
 
 Note that this isn't a production-ready installation; it's only meant as an alternative for [the original docker-compose installation](https://github.com/merico-dev/lake/blob/main/docker-compose.yml) should you prefer K8s.
 
-## 2 Usage:
+## Usage:
 
 ```yaml
 tools:

diff --git a/docs/plugins/github-repo-scaffolding-golang.md b/docs/plugins/github-repo-scaffolding-golang.md
@@ -1,4 +1,4 @@
-## 1 `github-repo-scaffolding-golang` Plugin
+# `github-repo-scaffolding-golang` Plugin
 
 This plugin bootstraps a GitHub repo with scaffolding code for a Golang web application.
 
@@ -17,7 +17,7 @@ If you don't know how to create this token, check out:
 
 *2. If the `Update` interface is called, the repo on github will be completely removed and recreated. However, given our current implementation, this interface shall not be called, as of in v0.2.0.*
 
-## 2 Usage
+## Usage
 
 **Please note that the `owner` parameter is case-sensitive.**
 
@@ -50,7 +50,7 @@ The "branch" in the example above is "main", but you can adjust accordingly.
 
 Currently, all the parameters in the example above are mandatory.
 
-## 3. Outputs
+## Outputs
 
 This plugin has three outputs:
 

diff --git a/docs/plugins/githubactions-golang.md b/docs/plugins/githubactions-golang.md
@@ -1,8 +1,8 @@
-## 1 `githubactions-golang` Plugin
+# `githubactions-golang` Plugin
 
 This plugin creates some Golang GitHub Actions workflows.
 
-## 2 Usage
+## Usage
 
 _This plugin depends on the following environment variable:_
 
@@ -62,7 +62,7 @@ tools:
 
 Some parameters are optional. See the default values and optional parameters in the example above.
 
-## 3. Use Together with the `github-repo-scaffolding-golang` Plugin
+## Use Together with the `github-repo-scaffolding-golang` Plugin
 
 This plugin can be used together with the `github-repo-scaffolding-golang` plugin (see document [here](./github-repo-scaffolding-golang.md).)
 

diff --git a/docs/plugins/githubactions-nodejs.md b/docs/plugins/githubactions-nodejs.md
@@ -1,8 +1,8 @@
-## 1 `githubactions-nodejs` Plugin
+# `githubactions-nodejs` Plugin
 
 This plugin creates Nodejs GitHub Actions workflows.
 
-## 2 Usage:
+## Usage:
 
 _This plugin depends on an environment variable "GITHUB_TOKEN". Set it before using this plugin._
 

diff --git a/docs/plugins/githubactions-python.md b/docs/plugins/githubactions-python.md
@@ -1,8 +1,8 @@
-## 1 `githubactions-python` Plugin
+# `githubactions-python` Plugin
 
 This plugin creates Python GitHub Actions workflows.
 
-## 2 Usage:
+## Usage:
 
 _This plugin depends on an environment variable "GITHUB_TOKEN". Set it before using this plugin._
 

diff --git a/docs/plugins/gitlabci-golang.md b/docs/plugins/gitlabci-golang.md
@@ -1,8 +1,8 @@
-## 1 `gitlabci-golang` Plugin
+# `gitlabci-golang` Plugin
 
 This plugin creates Golang GitLab CI workflow.
 
-## 2 Usage:
+## Usage:
 
 _This plugin depends on an environment variable "GITLAB_TOKEN", which is your GitLab personal access token. Set it before using this plugin._
 

diff --git a/docs/plugins/jenkins.md b/docs/plugins/jenkins.md
@@ -1,8 +1,8 @@
-## 1 `jenkins` Plugin
+# `jenkins` Plugin
 
 This plugin installs [jenkins](https://jenkins.io) in an existing Kubernetes cluster using the Helm chart.
 
-## 2 Usage:
+## Usage:
 
 NOTICE:
 

diff --git a/docs/plugins/jira-github-integ.md b/docs/plugins/jira-github-integ.md
@@ -1,8 +1,8 @@
-## 1 `jira-github-integ` Plugin
+# `jira-github-integ` Plugin
 
 This plugin integrates Jira with your GitHub repo.
 
-## 2 Usage:
+## Usage:
 
 _Please confirm the preconditions:_
 

diff --git a/docs/plugins/kube-prometheus.md b/docs/plugins/kube-prometheus.md
@@ -1,8 +1,8 @@
-## 1 `kube-prometheus` Plugin
+# `kube-prometheus` Plugin
 
 This plugin installs [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) in an existing Kubernetes cluster using the Helm chart.
 
-## 2 Usage:
+## Usage:
 
 ```yaml
 tools:

diff --git a/docs/plugins/openldap.md b/docs/plugins/openldap.md
@@ -1,8 +1,8 @@
-## 1 `openldap` Plugin
+# `openldap` Plugin
 
 This plugin installs [OpenLDAP](https://www.openldap.org/) in an existing Kubernetes cluster using the Helm chart. Please at least make sure your Kubernetes's version is greater than 1.18.
 
-## 2 Usage:
+## Usage:
 
 ```yaml
 tools:

diff --git a/docs/plugins/trello-github-integ.md b/docs/plugins/trello-github-integ.md
@@ -1,8 +1,8 @@
-## 1 `trello-github-integ` Plugin
+# `trello-github-integ` Plugin
 
 This plugin creates a new GitHub Actions workflow(trello-github-integration) and uploads it to your GitHub repo.
 
-## 2 Usage:
+## Usage:
 
 This plugin depends on and can be used together with the `trello` plugin (see document [here](./trello.md)).
 

diff --git a/docs/plugins/trello.md b/docs/plugins/trello.md
@@ -1,8 +1,8 @@
-## 1 `trello` Plugin
+# `trello` Plugin
 
 This plugin creates a new Trello board and lists.
 
-## 2 Usage:
+## Usage:
 
 _This plugin depends on the following two environment variables:_
 
@@ -11,7 +11,7 @@ _This plugin depends on the following two environment variables:_
 
 Set the values accordingly before using this plugin.
 
-## 3 Tips:
+## Tips:
 _Trello board description is managed by DevStream, please don't modify it._
 
 To create a Trello API key and token, see [here](https://trello.com/app-key).
@@ -37,7 +37,7 @@ Replace the following from the config above:
 - `YOUR_REPO_NAME`
 - `KANBAN_BOARD_NAME`
 
-## 3. Outputs
+## Outputs
 
 This plugin has four outputs: