From 5674c06001df38485032e9d5e414d4d6dc662377 Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Thu, 7 Apr 2022 16:50:04 +0800 Subject: [PATCH] docs: add a doc of docs, and refactor existing docs --- docs/best_practices.md | 8 +++ docs/best_practices/gitops.md | 6 ++ docs/commands_in_detail/verify.md | 2 +- docs/conf.py | 4 +- docs/creating_a_document.md | 64 +++++++++++++++++++ docs/index.md | 3 + docs/plugins.md | 23 +++++++ docs/plugins/argocd.md | 4 +- docs/plugins/argocdapp.md | 7 +- docs/plugins/devlake.md | 4 +- .../plugins/github-repo-scaffolding-golang.md | 6 +- docs/plugins/githubactions-golang.md | 6 +- docs/plugins/githubactions-nodejs.md | 4 +- docs/plugins/githubactions-python.md | 4 +- docs/plugins/gitlabci-golang.md | 4 +- docs/plugins/jenkins.md | 4 +- docs/plugins/jira-github-integ.md | 4 +- docs/plugins/kube-prometheus.md | 4 +- docs/plugins/openldap.md | 4 +- docs/plugins/trello-github-integ.md | 4 +- docs/plugins/trello.md | 8 +-- 21 files changed, 141 insertions(+), 36 deletions(-) create mode 100644 docs/best_practices.md create mode 100644 docs/creating_a_document.md create mode 100644 docs/plugins.md diff --git a/docs/best_practices.md b/docs/best_practices.md new file mode 100644 index 000000000..1b78dd3db --- /dev/null +++ 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 index cd83869ca..8feb56f41 100644 --- 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 +--- +``` \ No newline at end of file diff --git a/docs/commands_in_detail/verify.md b/docs/commands_in_detail/verify.md index 0a7503498..cbb2c0dc4 100644 --- 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 index 2b67f678e..6ff7509f1 100644 --- 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 new file mode 100644 index 000000000..bae295f30 --- /dev/null +++ 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 +--- +``` +```` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d478133d3..6781019d9 100644 --- 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 ⧉ Blog ⧉ diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 000000000..dbaf651d5 --- /dev/null +++ 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 index b789ed8c2..885dd81bf 100644 --- 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 index 12163ca15..3a39170f1 100644 --- 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 index dd647a7de..b83cc6cf1 100644 --- 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 index 9f84b67ba..cfdac3533 100644 --- 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 index b430a30a1..b03acb8aa 100644 --- 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 index b084ee502..48dbdf2e8 100644 --- 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 index 22b2056bf..2aa5d626d 100644 --- 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 index 45810176a..b104cb8be 100644 --- 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 index 9f0e679fa..b33574958 100644 --- 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 index 437b55f84..f73a5a3fe 100644 --- 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 index c07867708..5c9370f2a 100644 --- 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 index ff22f635a..dee308ed7 100644 --- 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 index c85b4ba10..eddc8c0dd 100644 --- 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 index 90bd556b2..433c4e296 100644 --- 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: