Skip to content

Commit 141396d

Browse files
Samreaypre-commit-ci[bot]henryiiiCopilot
authored
feat: adding mkdocs into guides and cookiecutter template (#662)
* Initial mkdocs additions * Updating mkdocs documentation * Updating mkdocs * Updating copier * I am dumb * Newline * Ensuring copier and cookiecutter work * style: pre-commit fixes * WIP: some additions Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * fix: can't make a directory conditional Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * style: pre-commit fixes * fix: minor fixup from looking at the diff Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * fix: some styling corrections Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * ci: update for new option Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * chore: more style adjustments Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore: colour -> color Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * chore: a few more updates inspired by copilot Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * chore: fix one more space Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * fix: serve or build mkdocs Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 7b1bfe1 commit 141396d

19 files changed

Lines changed: 629 additions & 120 deletions

‎.github/workflows/reusable-cookie.yml‎

Lines changed: 33 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -46,47 +46,49 @@ jobs:
4646
run: uv tool install nox
4747

4848
- name: Test pybind11
49-
run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs)'
49+
run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs, sphinx)'
5050

5151
- name: Test scikit-build
52-
run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs)'
52+
run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, sphinx)'
5353

5454
- name: Test poetry
55-
run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs)'
55+
run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs, sphinx)'
5656

5757
- name: Test flit
58-
run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs)'
58+
run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs, mkdocs)'
5959

6060
- name: Test uv
61-
run: nox -s 'tests(uv, novcs)'
61+
run: nox -s 'tests(uv, novcs, sphinx)'
6262

6363
- name: Test pdm
64-
run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs)'
64+
run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs, sphinx)'
6565

6666
- name: Test maturin
67-
run: nox -s 'tests(maturin, novcs)'
67+
run: nox -s 'tests(maturin, novcs, sphinx)'
6868

6969
- name: Test hatch
70-
run: nox -s 'tests(hatch, novcs)' -s 'tests(hatch, vcs)'
70+
run: nox -s 'tests(hatch, novcs, sphinx)' -s 'tests(hatch, vcs, sphinx)'
7171

7272
- name: Test setuptools PEP 621
73-
run: nox -s 'tests(setuptools, novcs)' -s 'tests(setuptools, vcs)'
73+
run:
74+
nox -s 'tests(setuptools, novcs, sphinx)' -s 'tests(setuptools, vcs,
75+
sphinx)'
7476

7577
- name: Native poetry tooling
7678
if: matrix.python-version != 'pypy-3.11'
7779
run: |
78-
nox -s 'native(poetry, novcs)'
79-
nox -s 'native(poetry, vcs)'
80+
nox -s 'native(poetry, novcs, sphinx)'
81+
nox -s 'native(poetry, vcs, sphinx)'
8082
8183
- name: Native pdm tooling
82-
run: nox -s 'native(pdm, novcs)' -s 'native(pdm, vcs)'
84+
run: nox -s 'native(pdm, novcs, sphinx)' -s 'native(pdm, vcs, sphinx)'
8385

8486
- name: Activate MSVC for Meson
8587
if: runner.os == 'Windows'
8688
uses: ilammy/msvc-dev-cmd@v1
8789

8890
- name: Test meson-python
89-
run: nox -s 'tests(mesonpy, novcs)'
91+
run: nox -s 'tests(mesonpy, novcs, sphinx)'
9092

9193
- name: Compare copier template generation
9294
run: nox -s compare_copier
@@ -114,52 +116,52 @@ jobs:
114116

115117
- name: Test pybind11
116118
run: |
117-
nox -s 'nox(pybind11, vcs)'
118-
nox -s 'nox(pybind11, vcs)' -- docs
119+
nox -s 'nox(pybind11, vcs, sphinx)'
120+
nox -s 'nox(pybind11, vcs, sphinx)' -- docs
119121
120122
- name: Test scikit-build
121123
run: |
122-
nox -s 'nox(skbuild, vcs)'
123-
nox -s 'nox(skbuild, vcs)' -- docs
124+
nox -s 'nox(skbuild, vcs, sphinx)'
125+
nox -s 'nox(skbuild, vcs, mkdocs)' -- docs
124126
125127
- name: Test poetry
126128
run: |
127-
nox -s 'nox(poetry, novcs)'
128-
nox -s 'nox(poetry, novcs)' -- docs
129+
nox -s 'nox(poetry, novcs, sphinx)'
130+
nox -s 'nox(poetry, novcs, mkdocs)' -- docs
129131
130132
- name: Test flit
131133
run: |
132-
nox -s 'nox(flit, novcs)'
133-
nox -s 'nox(flit, novcs)' -- docs
134+
nox -s 'nox(flit, novcs, mkdocs)'
135+
nox -s 'nox(flit, novcs, mkdocs)' -- docs
134136
135137
- name: Test pdm
136138
run: |
137-
nox -s 'nox(pdm, vcs)'
138-
nox -s 'nox(pdm, vcs)' -- docs
139+
nox -s 'nox(pdm, vcs, sphinx)'
140+
nox -s 'nox(pdm, vcs, sphinx)' -- docs
139141
140142
- name: Test maturin
141143
run: |
142-
nox -s 'nox(maturin, novcs)'
143-
nox -s 'nox(maturin, novcs)' -- docs
144+
nox -s 'nox(maturin, novcs, sphinx)'
145+
nox -s 'nox(maturin, novcs, sphinx)' -- docs
144146
145147
- name: Test hatch
146148
run: |
147-
nox -s 'nox(hatch, vcs)'
148-
nox -s 'nox(hatch, vcs)' -- docs
149+
nox -s 'nox(hatch, vcs, mkdocs)'
150+
nox -s 'nox(hatch, vcs, mkdocs)' -- docs
149151
150152
- name: Test setuptools PEP 621
151153
run: |
152-
nox -s 'nox(setuptools, vcs)'
153-
nox -s 'nox(setuptools, vcs)' -- docs
154+
nox -s 'nox(setuptools, vcs, sphinx)'
155+
nox -s 'nox(setuptools, vcs, sphinx)' -- docs
154156
155157
- name: Activate MSVC for Meson
156158
if: runner.os == 'Windows'
157159
uses: ilammy/msvc-dev-cmd@v1
158160

159161
- name: Test meson-python
160162
run: |
161-
nox -s 'nox(mesonpy, novcs)'
162-
nox -s 'nox(mesonpy, novcs)' -- docs
163+
nox -s 'nox(mesonpy, novcs, sphinx)'
164+
nox -s 'nox(mesonpy, novcs, sphinx)' -- docs
163165
164166
dist:
165167
name: Distribution build

‎cookiecutter.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"mesonpy",
1919
"maturin"
2020
],
21+
"docs": ["sphinx", "mkdocs"],
2122
"vcs": true,
2223
"__year": "{% now 'utc', '%Y' %}",
2324
"__project_slug": "{{ cookiecutter.project_name | lower | replace('-', '_') | replace('.', '_') }}",
@@ -45,6 +46,11 @@
4546
"mesonpy": "Meson-python - Compiled C++ (also good)",
4647
"maturin": "Maturin - Compiled Rust (recommended)"
4748
},
49+
"docs": {
50+
"__prompt__": "Choose your documentation tool",
51+
"sphinx": "Sphinx",
52+
"mkdocs": "MkDocs"
53+
},
4854
"vcs": "Use version control for versioning"
4955
}
5056
}

‎copier.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,14 @@ backend:
8282
"Maturin - Compiled Rust (recommended)": maturin
8383
# [[[end]]]
8484

85+
# [[[cog print(cc.docs.yaml()) ]]]
86+
docs:
87+
help: Choose your documentation tool
88+
choices:
89+
"Sphinx": sphinx
90+
"MkDocs": mkdocs
91+
# [[[end]]]
92+
8593
# [[[cog print(cc.vcs.yaml()) ]]]
8694
vcs:
8795
type: bool

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ scientists and research software engineers. The repository contains:
1111
## Contributing to the documentation
1212

1313
To build locally, install rbenv (remember to run `rbenv init` after installing,
14-
and `rbenv install 3.1.2`). Then:
14+
and `rbenv install 3.4.1`). Then:
1515

1616
```bash
1717
bundle install

0 commit comments

Comments
 (0)