Skip to content

Commit 7ec64b9

Browse files
jgfranco17jgfranco17
authored
DOCS: Add mkdocs pages (#2)
* feat: add base docs * ci: run integration test on src code changes * feat: add CLI docs * ci: add deployment workflow * docs: add usage to nav
1 parent 7c3627c commit 7ec64b9

18 files changed

Lines changed: 778 additions & 2 deletions

‎.github/workflows/cicd.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ on:
88
pull_request:
99
branches:
1010
- main
11+
paths-ignore:
12+
- "docs/**"
1113

1214
jobs:
1315
lint:

‎.github/workflows/docs.yaml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Deploy Docs Site
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "requirements.txt"
9+
- "mkdocs.yml"
10+
- "docs/**"
11+
- "**.md"
12+
13+
jobs:
14+
build-mkdocs:
15+
name: Build pages
16+
runs-on: ubuntu-latest
17+
if: ${{ github.event.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v3
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v4
25+
with:
26+
python-version: "3.11"
27+
28+
- name: Install dependencies
29+
run: |
30+
pip install --upgrade pip
31+
pip install -r requirements.txt
32+
mkdocs --version
33+
34+
- name: Build site pages
35+
run: |
36+
mkdocs build --clean --strict
37+
38+
- name: Setup GitHub Pages
39+
uses: actions/configure-pages@v3
40+
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: ./site
45+
46+
deploy-pages:
47+
name: Deploy to GitHub Pages
48+
if: ${{ github.ref == 'refs/heads/main' }}
49+
runs-on: ubuntu-latest
50+
needs: build-mkdocs
51+
52+
permissions:
53+
pages: write
54+
id-token: write
55+
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
60+
steps:
61+
- name: Deploy to GitHub Pages
62+
id: deployment
63+
uses: actions/deploy-pages@v4

‎.github/workflows/integration-test.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ name: Integration Test
55
pull_request:
66
branches:
77
- main
8+
paths:
9+
- "integration/**"
10+
- "**/*.go"
811
push:
912
branches:
1013
- main

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ htmlcov/
1515
# Virtual environments
1616
*venv
1717

18+
# Documentation
19+
site/
20+
1821
# Local development
1922
.vscode
2023
.idea

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ repos:
5050
hooks:
5151
- id: markdownlint
5252
args: [--config, ".markdownlint.yaml"]
53+
exclude: docs/cli/
5354

5455
# Security
5556
- repo: https://github.com/Yelp/detect-secrets

‎cli/core/commands.go‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,13 @@ package core
33
import (
44
"context"
55
"fmt"
6+
"os"
67

78
"github.com/spf13/cobra"
89

910
"github.com/jgfranco17/devops/cli/config"
1011
"github.com/jgfranco17/devops/cli/executor"
12+
"github.com/jgfranco17/devops/internal/doc"
1113
)
1214

1315
type BashExecutor interface {
@@ -76,3 +78,32 @@ func GetDoctorCommand(shellExecutor BashExecutor) *cobra.Command {
7678
}
7779
return cmd
7880
}
81+
82+
func GetDocsCommand() *cobra.Command {
83+
var outputFile string
84+
cmd := &cobra.Command{
85+
Use: "docs",
86+
Short: "Generate documentation for the CLI",
87+
Long: "Generate markdown documentation for all available commands and their usage.",
88+
Hidden: true,
89+
Args: cobra.NoArgs,
90+
RunE: func(cmd *cobra.Command, args []string) error {
91+
rootCmd := cmd.Root()
92+
docs, err := doc.GenerateMarkdown(rootCmd)
93+
if err != nil {
94+
return fmt.Errorf("failed to generate docs: %w", err)
95+
}
96+
97+
if err := os.WriteFile(outputFile, []byte(docs), 0644); err != nil {
98+
return fmt.Errorf("failed to write docs to file %s: %w", outputFile, err)
99+
}
100+
fmt.Fprintf(cmd.OutOrStdout(), "Documentation written to %s\n", outputFile)
101+
return nil
102+
},
103+
SilenceUsage: true,
104+
SilenceErrors: true,
105+
}
106+
107+
cmd.Flags().StringVarP(&outputFile, "output", "o", "docs/cli/devops.md", "Output file path")
108+
return cmd
109+
}

‎devops-definition.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: devops-common
1+
name: devops
22
description: DevOps CLI - Simplifying your CI/CD pipelines
33
version: 0.0.2
44
repo_url: https://github.com/jgfranco17/devops

‎docs/cli/devops.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# devops CLI Documentation
2+
3+
**Version:** 0.0.2
4+
5+
**Description:** DevOps: Simplifying your CI/CD pipelines.
6+
7+
## Usage
8+
9+
```bash
10+
devops [command] [flags] [arguments]
11+
```
12+
13+
## Global Flags
14+
15+
| Flag | Short | Type | Description |
16+
| --------- | ----- | ------ | ----------------------------------- |
17+
| --file | -f | string | Path to the project definition file |
18+
| --verbose | -v | count | Increase verbosity (-v or -vv) |
19+
20+
## Commands
21+
22+
### build
23+
24+
**Description:** Run the build operations
25+
26+
Build the project according to the configuration..
27+
28+
**Usage:**
29+
30+
```bash
31+
devops build
32+
```
33+
34+
### completion
35+
36+
**Description:** Generate the autocompletion script for the specified shell
37+
38+
Generate the autocompletion script for devops for the specified shell.
39+
See each sub-command's help for details on how to use the generated script.
40+
41+
**Usage:**
42+
43+
```bash
44+
devops completion
45+
```
46+
47+
### bash
48+
49+
**Description:** Generate the autocompletion script for bash
50+
51+
Generate the autocompletion script for the bash shell.
52+
53+
This script depends on the 'bash-completion' package.
54+
If it is not installed already, you can install it via your OS's package manager.
55+
56+
To load completions in your current shell session:
57+
58+
source <(devops completion bash)
59+
60+
To load completions for every new session, execute once:
61+
62+
#### Linux:
63+
64+
devops completion bash > /etc/bash_completion.d/devops
65+
66+
#### macOS:
67+
68+
devops completion bash > $(brew --prefix)/etc/bash_completion.d/devops
69+
70+
You will need to start a new shell for this setup to take effect.
71+
72+
**Usage:**
73+
```bash
74+
devops completion bash
75+
```
76+
77+
**Flags:**
78+
79+
| Flag | Short | Type | Description |
80+
|------|-------|------|-------------|
81+
| --no-descriptions | | bool | disable completion descriptions |
82+
83+
84+
### fish
85+
86+
**Description:** Generate the autocompletion script for fish
87+
88+
Generate the autocompletion script for the fish shell.
89+
90+
To load completions in your current shell session:
91+
92+
devops completion fish | source
93+
94+
To load completions for every new session, execute once:
95+
96+
devops completion fish > ~/.config/fish/completions/devops.fish
97+
98+
You will need to start a new shell for this setup to take effect.
99+
100+
**Usage:**
101+
```bash
102+
devops completion fish [flags]
103+
```
104+
105+
**Flags:**
106+
107+
| Flag | Short | Type | Description |
108+
|------|-------|------|-------------|
109+
| --no-descriptions | | bool | disable completion descriptions |
110+
111+
112+
### powershell
113+
114+
**Description:** Generate the autocompletion script for powershell
115+
116+
Generate the autocompletion script for powershell.
117+
118+
To load completions in your current shell session:
119+
120+
devops completion powershell | Out-String | Invoke-Expression
121+
122+
To load completions for every new session, add the output of the above command
123+
to your powershell profile.
124+
125+
**Usage:**
126+
```bash
127+
devops completion powershell [flags]
128+
```
129+
130+
**Flags:**
131+
132+
| Flag | Short | Type | Description |
133+
|------|-------|------|-------------|
134+
| --no-descriptions | | bool | disable completion descriptions |
135+
136+
137+
### zsh
138+
139+
**Description:** Generate the autocompletion script for zsh
140+
141+
Generate the autocompletion script for the zsh shell.
142+
143+
If shell completion is not already enabled in your environment you will need
144+
to enable it. You can execute the following once:
145+
146+
echo "autoload -U compinit; compinit" >> ~/.zshrc
147+
148+
To load completions in your current shell session:
149+
150+
source <(devops completion zsh)
151+
152+
To load completions for every new session, execute once:
153+
154+
#### Linux:
155+
156+
devops completion zsh > "${fpath[1]}/_devops"
157+
158+
#### macOS:
159+
160+
devops completion zsh > $(brew --prefix)/share/zsh/site-functions/_devops
161+
162+
You will need to start a new shell for this setup to take effect.
163+
164+
**Usage:**
165+
```bash
166+
devops completion zsh [flags]
167+
```
168+
169+
**Flags:**
170+
171+
| Flag | Short | Type | Description |
172+
|------|-------|------|-------------|
173+
| --no-descriptions | | bool | disable completion descriptions |
174+
175+
### doctor
176+
177+
**Description:** Validate your configuration
178+
179+
Run checks on your configuration file to ensure it is ready for use.
180+
181+
**Usage:**
182+
183+
```bash
184+
devops doctor
185+
```
186+
187+
### help
188+
189+
**Description:** Help about any command
190+
191+
Help provides help for any command in the application.
192+
Simply type devops help [path to command] for full details.
193+
194+
**Usage:**
195+
196+
```bash
197+
devops help [command]
198+
```
199+
200+
### test
201+
202+
**Description:** Run the test operations
203+
204+
Run the designated test operations.
205+
206+
**Usage:**
207+
208+
```bash
209+
devops test
210+
```

0 commit comments

Comments
 (0)