-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.qmd
88 lines (67 loc) · 2.13 KB
/
README.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
---
format: gfm
execute:
echo: false
output: asis
---
# mkdocs-mike
```{python}
import ccbr_actions.docs
action = ccbr_actions.docs.parse_action_yaml('action.yml')
print(ccbr_actions.docs.action_markdown_desc(action))
```
This action is designed to be used with a repository that uses mkdocs to generate documentation and mike to deploy it to github pages. The action will checkout the repository, install the necessary python packages, build the documentation, and deploy it to the specified branch.
## Usage
Any python requirements for your docs website (mkdocs, mike, other extensions) should be placed in `docs/requirements.txt`.
You will also need an mkdocs config file `mkdocs.yml` in the root of your repository.
To properly configure mike for your website, you will also need to complete these one-time steps:
- delete any existing github workflows that deploy to github pages
- delete all files in `gh-pages` if the branch exists already
```sh
git switch gh-pages
git rm -rf $(git ls-files)
git commit -m 'docs: delete gh-pages files to prepare for mike'
```
- check out the previous release tag and deploy it
```sh
git checkout v1.0.0
mike deploy 1.0 latest --push --update-aliases --branch gh-pages
```
We recommend using just the major and minor components of the version without the leading v.
- set the default landing page:
```sh
mike set-default latest
```
- deploy the dev version from main
```sh
git switch main
mike deploy dev --push --update-aliases --branch gh-pages
```
### Basic example
[docs-mkdocs.yml](/examples/docs-mkdocs.yml)
```yaml
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: CCBR/actions/mkdocs-mike@main
with:
github-token: ${{ github.token }}
```
### Customized inputs
```yaml
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: CCBR/actions/mkdocs-mike@main
with:
github-token: ${{ github.token }}
ccbr-actions-version: 0.1
python-version: 3.12
docs-branch: gh-pages
github-actor: "41898282+github-actions[bot]"
```
```{python}
print(ccbr_actions.docs.action_markdown_io(action))
```