Skip to content

Commit 5469068

Browse files
TohakerTohaker
authored
docs: GH-6 Adding mkdocs configuration (#7)
* chore: Adding devcontainer files and dependabot config * docs: Adding mkdocs configuration files
1 parent c651cf2 commit 5469068

7 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎.devcontainer/devcontainer.json‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
2+
// README at: https://github.com/devcontainers/templates/tree/main/src/go .
3+
{
4+
"name": "Go",
5+
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
6+
"image": "mcr.microsoft.com/devcontainers/go:2-1.25-trixie",
7+
8+
// Features to add to the dev container. More info: https://containers.dev/features.
9+
"features": {
10+
"ghcr.io/devcontainers-extra/features/mkdocs:2": {
11+
"plugins": "mkdocs-material mkdocs-exclude"
12+
},
13+
"ghcr.io/devcontainers/features/docker-in-docker:2": {
14+
"moby": false
15+
}
16+
},
17+
"customizations": {
18+
"vscode": {
19+
"extensions": [
20+
"github.vscode-github-actions",
21+
"redhat.vscode-yaml"
22+
]
23+
}
24+
}
25+
26+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
27+
// "forwardPorts": [],
28+
29+
// Use 'postCreateCommand' to run commands after the container is created.
30+
// "postCreateCommand": "go version",
31+
32+
// Configure tool-specific properties.
33+
// "customizations": {},
34+
35+
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
36+
// "remoteUser": "root"
37+
}

‎.github/dependabot.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# To get started with Dependabot version updates, you'll need to specify which
2+
# package ecosystems to update and where the package manifests are located.
3+
# Please see the documentation for more information:
4+
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5+
# https://containers.dev/guide/dependabot
6+
7+
version: 2
8+
updates:
9+
- package-ecosystem: "devcontainers"
10+
directory: "/"
11+
schedule:
12+
interval: weekly
13+
- package-ecosystem: "github-actions"
14+
directory: "/"
15+
schedule:
16+
interval: weekly
17+
- package-ecosystem: "go-mod"
18+
directory: "/"
19+
schedule:
20+
interval: weekly

‎.github/workflows/deploy-docs.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: deploy-docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- mkdocs.yml
9+
- omada/README.md
10+
- 'omada/docs/**'
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
deploy:
17+
runs-on: ubuntu-slim
18+
steps:
19+
- uses: actions/checkout@v6
20+
- name: Configure Git Credentials
21+
run: |
22+
git config user.name github-actions[bot]
23+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
24+
- uses: actions/setup-python@v6
25+
with:
26+
python-version: 3.x
27+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
28+
- uses: actions/cache@v5
29+
with:
30+
key: mkdocs-material-${{ env.cache_id }}
31+
path: ~/.cache
32+
restore-keys: |
33+
mkdocs-material-
34+
- run: pip install mkdocs-material mkdocs-exclude
35+
- run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/site

‎.vscode/settings.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"yaml.schemas": {
3+
"https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
4+
},
5+
"yaml.customTags": [
6+
"!ENV scalar",
7+
"!ENV sequence",
8+
"!relative scalar",
9+
"tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
10+
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
11+
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
12+
"tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
13+
]
14+
}

‎README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,32 @@ Or use the GitHub Actions workflow: **Actions → Generate SDK → Run workflow*
111111
3. A separate generation pass adds auth endpoints from `generator/auth-spec.yaml`
112112
4. The result is a single `omada` Go package in the `omada/` subdirectory
113113

114+
## Publishing docs
115+
116+
Docs are published using [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/).
117+
118+
If you've opened this repository in the `devcontainer`, `mkdocs` and all required plugins will already be installed and configured for you.
119+
120+
Otherwise, if you haven't done so already, follow their [getting started](https://squidfunk.github.io/mkdocs-material/getting-started) guide to set up your local environment.
121+
122+
You must also install the following extra plugins;
123+
- `mkdocs-exclude`
124+
125+
To preview the docs locally, just run
126+
127+
```sh
128+
mkdocs serve
129+
```
130+
131+
Or build to the `/site` directory with
132+
133+
```sh
134+
mkdocs build
135+
```
136+
137+
Whenever docs are generated with `go generate` and commited to the main branch, the docs will deploy and be available to view at `tohaker.github.io/omada-go-sdk`.
138+
139+
114140
## License
115141

116142
See [LICENSE](LICENSE).

‎mkdocs.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
site_name: Omada Go SDK
2+
site_url: https://tohaker.github.io/omada-go-sdk
3+
repo_url: https://github.com/Tohaker/omada-go-sdk
4+
theme:
5+
name: material
6+
docs_dir: omada
7+
plugins:
8+
- search
9+
- exclude:
10+
glob:
11+
- /.openapi-generator
12+
- /test
13+
- "*.go"
14+
- .openapi-generator-ignore

0 commit comments

Comments
 (0)