Skip to content

Commit 609ca91

Browse files
per1234per1234
committed
Add documentation for versioned website with generated Cobra command reference
1 parent 58fa673 commit 609ca91

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

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

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
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+
- [`Taskfile.yml`](assets/check-prettier-formatting/Taskfile.yml) - documentation formatting task.
29+
- Merge into `Taskfile.yml`
30+
- [`docsgen`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen) - command line reference generator.
31+
- Install to: `docsgen/`
32+
- [`.gitkeep`](assets/deploy-cobra-mkdocs-versioned-poetry/.gitkeep) - empty placeholder file to preserve the generated documentation's target folder in the repository.
33+
- Install to: `docs/commands/`
34+
35+
### Dependencies
36+
37+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#dependencies) for the instructions to install the dependencies
38+
39+
### Configuration
40+
41+
#### Taskfile
42+
43+
Set the `PROJECT_NAME` variable to the project name.
44+
45+
If there are any additional documentation generation tasks, add them to the `docs:generate` umbrella task.
46+
47+
#### `docsgen`
48+
49+
- [`go.mod`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod) - replace `MODULE_NAME` with the project's module name.
50+
- [`main.go`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go) - replace `CLI_PACKAGE_NAME` with the project's Cobra CLI package name
51+
52+
Run the following command from the `docsgen/` folder:
53+
54+
```
55+
go mod tidy
56+
```
57+
58+
Commit the resulting `docsgen/go.sum` file to the repository.
59+
60+
#### Configure base assets
61+
62+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#configuration).
63+
64+
#### Define "dev" source branch
65+
66+
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:
67+
68+
- `on.push.branches[0]` in `deploy-cobra-mkdocs-versioned-poetry.yml`
69+
- `DEV_BRANCHES` in [`siteversion/siteversion.py`](assets/deploy-mkdocs-versioned/siteversion/siteversion.py)
70+
71+
#### Configure `.gitignore`
72+
73+
Add the following to `.gitignore`:
74+
75+
```
76+
/docsgen/<application executable>
77+
/docsgen/<application executable>.exe
78+
/docs/commands/*.md
79+
```
80+
81+
(where "`<application executable>`" is the filename of the application's executable, as defined in the Taskfile `PROJECT_NAME` variable.
82+
83+
### Setup
84+
85+
1. Checkout the branch of the repository that contains the documentation source files for the "dev" version of the website (e.g., `main`).
86+
1. Run the following command:
87+
```
88+
task docs:generate
89+
```
90+
1. Follow the remaining setup steps from the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#setup).
91+
92+
### Readme badge
93+
94+
Markdown badge:
95+
96+
```markdown
97+
[![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)
98+
```
99+
100+
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)).
101+
102+
---
103+
104+
Asciidoc badge:
105+
106+
```adoc
107+
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"]
108+
```
109+
110+
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)).
111+
112+
## Website versioning
113+
114+
See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#website-versioning) for an explanation of how the versioning works.
115+
116+
## Commit message
117+
118+
```
119+
Add CI workflow to deploy a versioned MkDocs-based website to GitHub Pages
120+
121+
On every push to the repository's default branch or release branch, generate a command line reference and deploy the
122+
repository's MkDocs-based static website to GitHub Pages.
123+
124+
Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
125+
for the reader to be able to access the documentation for the specific version of the project they are using.
126+
127+
The documentation system provides access to:
128+
129+
- The tip of the default branch ("dev")
130+
- The latest release ("latest")
131+
- Each minor version series (e.g., "1.2")
132+
133+
The website version is selectable via a menu on the website as well as the URL of each documentation page.
134+
```
135+
136+
## PR message
137+
138+
```markdown
139+
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/).
140+
141+
Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
142+
for the reader to be able to access the documentation for the specific version of the project they are using.
143+
144+
With the help of [mike](https://github.com/jimporter/mike), the documentation system provides access to:
145+
146+
- The tip of the default branch ("dev")
147+
- The latest release ("latest")
148+
- Each minor version series (e.g., "1.2")
149+
150+
The website version is selectable via a menu on the website as well as the URL of each documentation page.
151+
```

0 commit comments

Comments
 (0)