Skip to content

Commit f0f70c1

Browse files
per1234per1234
committed
Add documentation for versioned website with generated Cobra command reference
1 parent 4944e15 commit f0f70c1

File tree

1 file changed

+147
-0
lines changed

1 file changed

+147
-0
lines changed

‎workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# "Deploy Website" workflow (Cobra, versioned, MkDocs, Poetry)
2+
3+
Generate a command line reference for projects using [the Cobra Go module](https://cobra.dev/) and deploy a versioned [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).
4+
5+
This uses Cobra's built-in Markdown documentation generation capability:<br/>
6+
https://github.com/spf13/cobra/blob/master/doc/md_docs.md
7+
8+
Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important for the reader to be able to access the documentation for the specific version of the project they are using.
9+
The system provides a easy access to a website version for the documentation content at:
10+
11+
- The tip of the default branch ("dev")
12+
- The latest release ("latest")
13+
- Each minor version series (e.g., "1.2")
14+
15+
The website version is selectable via a menu on the website as well as the URL of each documentation page.
16+
17+
## Installation
18+
19+
### Workflow
20+
21+
Install the [`deploy-cobra-mkdocs-versioned-poetry.yml`](deploy-cobra-mkdocs-versioned-poetry.yml) GitHub Actions workflow to `.github/workflows/`
22+
23+
### Assets
24+
25+
- Base assets - See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#assets)
26+
- [`Taskfile.yml`](assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml) - documentation generation tasks.
27+
- Install to: repository root (or merge into the existing `Taskfile.yml`).
28+
- [`docsgen`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen) - command line reference generator.
29+
- Install to: `docsgen/`
30+
31+
### Dependencies
32+
33+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#dependencies) for the instructions to install the dependencies
34+
35+
### Configuration
36+
37+
#### Taskfile
38+
39+
Set the `PROJECT_NAME` variable to the project name.
40+
41+
If there are any additional documentation generation tasks, add them to the `docs:generate` umbrella task.
42+
43+
#### `docsgen`
44+
45+
- [`go.mod`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod) - replace `MODULE_NAME` with the project's module name.
46+
- [`main.go`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go) - replace `CLI_PACKAGE_NAME` with the project's Cobra CLI package name
47+
48+
Run the following command from the `docsgen/` folder:
49+
50+
```
51+
go mod tidy
52+
```
53+
54+
Commit the resulting `docsgen/go.sum` file to the repository.
55+
56+
#### Configure base assets
57+
58+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#configuration).
59+
60+
#### Define "dev" source branch
61+
62+
The system is configured for the repository branch used as the source for the "dev" website version having the name `main`. If the project's development branch has another name, then configure it:
63+
64+
- `on.push.branches[0]` in `deploy-cobra-mkdocs-versioned-poetry.yml`
65+
- `DEV_BRANCHES` in [`siteversion/siteversion.py`](assets/deploy-mkdocs-versioned/siteversion/siteversion.py)
66+
67+
#### Configure `.gitignore`
68+
69+
Add the following to `.gitignore`:
70+
71+
```
72+
/docsgen/<application executable>
73+
/docsgen/<application executable>.exe
74+
/docs/commands/*.md
75+
```
76+
77+
(where "`<application executable>`" is the filename of the application's executable, as defined in the Taskfile `PROJECT_NAME` variable.
78+
79+
### Setup
80+
81+
1. Checkout the branch of the repository that contains the documentation source files for the "dev" version of the website (e.g., `main`).
82+
1. Run the following command:
83+
```
84+
task docs:generate
85+
```
86+
1. Follow the remaining setup steps from the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#setup).
87+
88+
### Readme badge
89+
90+
Markdown badge:
91+
92+
```markdown
93+
[![Deploy Website status](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)
94+
```
95+
96+
Replace the `REPO_OWNER` and `REPO_NAME` placeholders in the URLs with the final repository owner and name ([example](https://raw.githubusercontent.com/arduino-libraries/ArduinoIoTCloud/master/README.md)).
97+
98+
---
99+
100+
Asciidoc badge:
101+
102+
```adoc
103+
image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg["Deploy Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml"]
104+
```
105+
106+
Define the `{repository-owner}` and `{repository-name}` attributes and use them throughout the readme ([example](https://raw.githubusercontent.com/arduino-libraries/WiFiNINA/master/README.adoc)).
107+
108+
## Website versioning
109+
110+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#website-versioning) for an explanation of how the versioning works.
111+
112+
## Commit message
113+
114+
```
115+
Add CI workflow to deploy a versioned MkDocs-based website to GitHub Pages
116+
117+
On every push to the repository's default branch or release branch, generate a command line reference and deploy the
118+
repository's MkDocs-based static website to GitHub Pages.
119+
120+
Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
121+
for the reader to be able to access the documentation for the specific version of the project they are using.
122+
123+
The documentation system provides access to:
124+
125+
- The tip of the default branch ("dev")
126+
- The latest release ("latest")
127+
- Each minor version series (e.g., "1.2")
128+
129+
The website version is selectable via a menu on the website as well as the URL of each documentation page.
130+
```
131+
132+
## PR message
133+
134+
```markdown
135+
On every push to the repository's default branch, generate a command line reference and deploy the repository's [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).
136+
137+
Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
138+
for the reader to be able to access the documentation for the specific version of the project they are using.
139+
140+
With the help of [mike](https://github.com/jimporter/mike), the documentation system provides access to:
141+
142+
- The tip of the default branch ("dev")
143+
- The latest release ("latest")
144+
- Each minor version series (e.g., "1.2")
145+
146+
The website version is selectable via a menu on the website as well as the URL of each documentation page.
147+
```

0 commit comments

Comments
 (0)